zig-mobile-runner 0.1.0

package/src/scenario.zig

@@ -0,0 +1,346 @@
+const std = @import("std");
+const fields = @import("scenario_fields.zig");
+const selector = @import("selector.zig");
+
+pub const Swipe = struct {
+    x1: i32,
+    y1: i32,
+    x2: i32,
+    y2: i32,
+    duration_ms: u32 = 300,
+};
+
+pub const WaitVisible = struct {
+    selector: selector.Selector,
+    timeout_ms: u64 = 5000,
+};
+
+pub const WaitAny = struct {
+    selectors: []selector.Selector,
+    timeout_ms: u64 = 5000,
+
+    pub fn deinit(self: WaitAny, allocator: std.mem.Allocator) void {
+        for (self.selectors) |wanted| wanted.deinit(allocator);
+        allocator.free(self.selectors);
+    }
+};
+
+pub const TypeText = struct {
+    selector: ?selector.Selector = null,
+    text: []const u8,
+
+    pub fn deinit(self: TypeText, allocator: std.mem.Allocator) void {
+        if (self.selector) |wanted| wanted.deinit(allocator);
+        allocator.free(self.text);
+    }
+};
+
+pub const EraseText = struct {
+    selector: ?selector.Selector = null,
+    max_chars: u32 = 80,
+
+    pub fn deinit(self: EraseText, allocator: std.mem.Allocator) void {
+        if (self.selector) |wanted| wanted.deinit(allocator);
+    }
+};
+
+pub const StepBlock = struct {
+    steps: []Step,
+
+    pub fn deinit(self: StepBlock, allocator: std.mem.Allocator) void {
+        for (self.steps) |step| step.deinit(allocator);
+        allocator.free(self.steps);
+    }
+};
+
+pub const ConditionalBlock = struct {
+    selector: selector.Selector,
+    timeout_ms: u64 = 0,
+    steps: []Step,
+
+    pub fn deinit(self: ConditionalBlock, allocator: std.mem.Allocator) void {
+        self.selector.deinit(allocator);
+        for (self.steps) |step| step.deinit(allocator);
+        allocator.free(self.steps);
+    }
+};
+
+pub const RepeatBlock = struct {
+    times: u32,
+    steps: []Step,
+
+    pub fn deinit(self: RepeatBlock, allocator: std.mem.Allocator) void {
+        for (self.steps) |step| step.deinit(allocator);
+        allocator.free(self.steps);
+    }
+};
+
+pub const ScrollDirection = enum {
+    down,
+    up,
+};
+
+pub const ScrollUntilVisible = struct {
+    selector: selector.Selector,
+    timeout_ms: u64 = 5000,
+    direction: ScrollDirection = .down,
+
+    pub fn deinit(self: ScrollUntilVisible, allocator: std.mem.Allocator) void {
+        self.selector.deinit(allocator);
+    }
+};
+
+pub const Step = union(enum) {
+    launch,
+    stop,
+    clear_state,
+    snapshot,
+    open_link: []const u8,
+    tap: selector.Selector,
+    type_text: TypeText,
+    press_back,
+    hide_keyboard,
+    swipe: Swipe,
+    erase_text: EraseText,
+    wait_visible: WaitVisible,
+    wait_not_visible: WaitVisible,
+    wait_any: WaitAny,
+    assert_visible: selector.Selector,
+    assert_not_visible: selector.Selector,
+    assert_none_visible: WaitAny,
+    assert_healthy_timeout_ms: u64,
+    optional: *Step,
+    when_visible: ConditionalBlock,
+    repeat: RepeatBlock,
+    scroll_until_visible: ScrollUntilVisible,
+    sleep_ms: u64,
+
+    pub fn deinit(self: Step, allocator: std.mem.Allocator) void {
+        switch (self) {
+            .open_link => |value| allocator.free(value),
+            .tap => |value| value.deinit(allocator),
+            .type_text => |value| value.deinit(allocator),
+            .erase_text => |value| value.deinit(allocator),
+            .wait_visible => |value| value.selector.deinit(allocator),
+            .wait_not_visible => |value| value.selector.deinit(allocator),
+            .wait_any => |value| value.deinit(allocator),
+            .assert_visible => |value| value.deinit(allocator),
+            .assert_not_visible => |value| value.deinit(allocator),
+            .assert_none_visible => |value| value.deinit(allocator),
+            .optional => |value| {
+                value.deinit(allocator);
+                allocator.destroy(value);
+            },
+            .when_visible => |value| value.deinit(allocator),
+            .repeat => |value| value.deinit(allocator),
+            .scroll_until_visible => |value| value.deinit(allocator),
+            else => {},
+        }
+    }
+};
+
+pub const Scenario = struct {
+    name: []const u8,
+    app_id: ?[]const u8 = null,
+    steps: []Step,
+
+    pub fn deinit(self: Scenario, allocator: std.mem.Allocator) void {
+        allocator.free(self.name);
+        if (self.app_id) |value| allocator.free(value);
+        for (self.steps) |step| step.deinit(allocator);
+        allocator.free(self.steps);
+    }
+};
+
+pub fn parseFile(allocator: std.mem.Allocator, path: []const u8) !Scenario {
+    const content = try std.fs.cwd().readFileAlloc(allocator, path, 16 * 1024 * 1024);
+    defer allocator.free(content);
+    return try parseSlice(allocator, content);
+}
+
+pub fn parseSlice(allocator: std.mem.Allocator, content: []const u8) !Scenario {
+    const parsed = try std.json.parseFromSlice(std.json.Value, allocator, content, .{});
+    defer parsed.deinit();
+    if (parsed.value != .object) return error.ScenarioMustBeObject;
+    const root = parsed.value.object;
+
+    const name = try fields.requiredString(allocator, root, "name");
+    errdefer allocator.free(name);
+    const app_id = try fields.optionalString(allocator, root, "appId");
+    errdefer if (app_id) |value| allocator.free(value);
+
+    const steps_value = root.get("steps") orelse return error.ScenarioMissingSteps;
+    if (steps_value != .array) return error.ScenarioStepsMustBeArray;
+    var steps = std.ArrayList(Step).empty;
+    errdefer {
+        for (steps.items) |step| step.deinit(allocator);
+        steps.deinit(allocator);
+    }
+    try appendParsedSteps(allocator, &steps, steps_value);
+
+    return .{
+        .name = name,
+        .app_id = app_id,
+        .steps = try steps.toOwnedSlice(allocator),
+    };
+}
+
+fn parseStep(allocator: std.mem.Allocator, value: std.json.Value) anyerror!Step {
+    if (value != .object) return error.StepMustBeObject;
+    const object = value.object;
+    var parsed = try parseRawStep(allocator, object);
+    errdefer parsed.deinit(allocator);
+
+    if (try fields.optionalBool(object, "optional", false)) {
+        const step_ptr = try allocator.create(Step);
+        errdefer allocator.destroy(step_ptr);
+        step_ptr.* = parsed;
+        return .{ .optional = step_ptr };
+    }
+
+    return parsed;
+}
+
+fn parseRawStep(allocator: std.mem.Allocator, object: std.json.ObjectMap) anyerror!Step {
+    const action_value = object.get("action") orelse return error.StepMissingAction;
+    if (action_value != .string) return error.StepActionMustBeString;
+    const action = action_value.string;
+
+    if (std.mem.eql(u8, action, "launch")) return .launch;
+    if (std.mem.eql(u8, action, "stop")) return .stop;
+    if (std.mem.eql(u8, action, "clearState")) return .clear_state;
+    if (std.mem.eql(u8, action, "snapshot")) return .snapshot;
+    if (std.mem.eql(u8, action, "pressBack")) return .press_back;
+    if (std.mem.eql(u8, action, "hideKeyboard")) return .hide_keyboard;
+    if (std.mem.eql(u8, action, "sleep")) return .{ .sleep_ms = try fields.optionalU64(object, "ms", 500) };
+    if (std.mem.eql(u8, action, "openLink")) return .{ .open_link = try fields.requiredStringOrError(allocator, object, "url", error.StepMissingUrl) };
+    if (std.mem.eql(u8, action, "tap")) return .{ .tap = try fields.parseSelectorField(allocator, object) };
+    if (std.mem.eql(u8, action, "typeText")) {
+        const wanted = if (object.get("selector")) |selector_value| try selector.parseFromJson(allocator, selector_value) else null;
+        errdefer if (wanted) |actual| actual.deinit(allocator);
+        return .{ .type_text = .{
+            .selector = wanted,
+            .text = try fields.requiredStringOrError(allocator, object, "text", error.StepMissingText),
+        } };
+    }
+    if (std.mem.eql(u8, action, "eraseText")) {
+        const wanted = if (object.get("selector")) |selector_value| try selector.parseFromJson(allocator, selector_value) else null;
+        errdefer if (wanted) |actual| actual.deinit(allocator);
+        return .{ .erase_text = .{
+            .selector = wanted,
+            .max_chars = @as(u32, @intCast(try fields.optionalU64(object, "maxChars", 80))),
+        } };
+    }
+    if (std.mem.eql(u8, action, "swipe")) return .{ .swipe = .{
+        .x1 = try fields.requiredI32OrError(object, "x1", error.StepMissingX1),
+        .y1 = try fields.requiredI32OrError(object, "y1", error.StepMissingY1),
+        .x2 = try fields.requiredI32OrError(object, "x2", error.StepMissingX2),
+        .y2 = try fields.requiredI32OrError(object, "y2", error.StepMissingY2),
+        .duration_ms = @as(u32, @intCast(try fields.optionalU64(object, "durationMs", 300))),
+    } };
+    if (std.mem.eql(u8, action, "waitVisible")) {
+        const wanted = try fields.parseSelectorField(allocator, object);
+        errdefer wanted.deinit(allocator);
+        return .{ .wait_visible = .{
+            .selector = wanted,
+            .timeout_ms = try fields.optionalU64(object, "timeoutMs", 5000),
+        } };
+    }
+    if (std.mem.eql(u8, action, "waitNotVisible")) {
+        const wanted = try fields.parseSelectorField(allocator, object);
+        errdefer wanted.deinit(allocator);
+        return .{ .wait_not_visible = .{
+            .selector = wanted,
+            .timeout_ms = try fields.optionalU64(object, "timeoutMs", 5000),
+        } };
+    }
+    if (std.mem.eql(u8, action, "waitAny")) {
+        const selectors = try fields.parseSelectorArrayField(allocator, object);
+        errdefer {
+            for (selectors) |wanted| wanted.deinit(allocator);
+            allocator.free(selectors);
+        }
+        return .{ .wait_any = .{
+            .selectors = selectors,
+            .timeout_ms = try fields.optionalU64(object, "timeoutMs", 5000),
+        } };
+    }
+    if (std.mem.eql(u8, action, "assertVisible")) return .{ .assert_visible = try fields.parseSelectorField(allocator, object) };
+    if (std.mem.eql(u8, action, "assertNotVisible")) return .{ .assert_not_visible = try fields.parseSelectorField(allocator, object) };
+    if (std.mem.eql(u8, action, "assertHealthy")) return .{ .assert_healthy_timeout_ms = try fields.optionalU64(object, "timeoutMs", 0) };
+    if (std.mem.eql(u8, action, "assertNoneVisible")) {
+        const selectors = try fields.parseSelectorArrayField(allocator, object);
+        errdefer {
+            for (selectors) |wanted| wanted.deinit(allocator);
+            allocator.free(selectors);
+        }
+        return .{ .assert_none_visible = .{
+            .selectors = selectors,
+            .timeout_ms = try fields.optionalU64(object, "timeoutMs", 0),
+        } };
+    }
+    if (std.mem.eql(u8, action, "optional")) {
+        const nested_value = object.get("step") orelse return error.OptionalStepMissingStep;
+        const nested = try allocator.create(Step);
+        errdefer allocator.destroy(nested);
+        nested.* = try parseStep(allocator, nested_value);
+        return .{ .optional = nested };
+    }
+    if (std.mem.eql(u8, action, "whenVisible")) {
+        const wanted = try fields.parseSelectorField(allocator, object);
+        errdefer wanted.deinit(allocator);
+        const timeout_ms = try fields.optionalU64(object, "timeoutMs", 0);
+        const steps = try parseStepsField(allocator, object);
+        errdefer {
+            for (steps) |step| step.deinit(allocator);
+            allocator.free(steps);
+        }
+        return .{ .when_visible = .{
+            .selector = wanted,
+            .timeout_ms = timeout_ms,
+            .steps = steps,
+        } };
+    }
+    if (std.mem.eql(u8, action, "repeat")) return .{ .repeat = .{
+        .times = @as(u32, @intCast(try fields.optionalU64(object, "times", 1))),
+        .steps = try parseStepsField(allocator, object),
+    } };
+    if (std.mem.eql(u8, action, "scrollUntilVisible")) {
+        const wanted = try fields.parseSelectorField(allocator, object);
+        errdefer wanted.deinit(allocator);
+        return .{ .scroll_until_visible = .{
+            .selector = wanted,
+            .timeout_ms = try fields.optionalU64(object, "timeoutMs", 5000),
+            .direction = try optionalDirection(object, "direction", .down),
+        } };
+    }
+
+    return error.UnknownScenarioAction;
+}
+
+fn appendParsedSteps(allocator: std.mem.Allocator, steps: *std.ArrayList(Step), value: std.json.Value) anyerror!void {
+    if (value != .array) return error.ScenarioStepsMustBeArray;
+    for (value.array.items) |step_value| {
+        try steps.append(allocator, try parseStep(allocator, step_value));
+    }
+}
+
+fn parseStepsField(allocator: std.mem.Allocator, object: std.json.ObjectMap) anyerror![]Step {
+    const steps_value = object.get("steps") orelse return error.StepBlockMissingSteps;
+    if (steps_value != .array) return error.StepBlockStepsMustBeArray;
+    var steps = std.ArrayList(Step).empty;
+    errdefer {
+        for (steps.items) |step| step.deinit(allocator);
+        steps.deinit(allocator);
+    }
+    try appendParsedSteps(allocator, &steps, steps_value);
+    return try steps.toOwnedSlice(allocator);
+}
+
+fn optionalDirection(object: std.json.ObjectMap, key: []const u8, default_value: ScrollDirection) !ScrollDirection {
+    const value = object.get(key) orelse return default_value;
+    if (value != .string) return error.OptionalFieldMustBeString;
+    if (std.mem.eql(u8, value.string, "down")) return .down;
+    if (std.mem.eql(u8, value.string, "up")) return .up;
+    return error.UnknownScrollDirection;
+}

package/src/scenario_fields.zig

@@ -0,0 +1,50 @@
+const std = @import("std");
+const json_fields = @import("json_fields.zig");
+const selector = @import("selector.zig");
+
+pub fn requiredString(allocator: std.mem.Allocator, object: std.json.ObjectMap, key: []const u8) ![]const u8 {
+    const value = try json_fields.requiredStringFromObject(object, key, error.RequiredStringMissing, error.RequiredFieldMustBeString);
+    return try allocator.dupe(u8, value);
+}
+
+pub fn requiredStringOrError(allocator: std.mem.Allocator, object: std.json.ObjectMap, key: []const u8, missing_error: anyerror) ![]const u8 {
+    const value = try json_fields.requiredStringFromObject(object, key, missing_error, error.RequiredFieldMustBeString);
+    return try allocator.dupe(u8, value);
+}
+
+pub fn optionalString(allocator: std.mem.Allocator, object: std.json.ObjectMap, key: []const u8) !?[]const u8 {
+    const value = try json_fields.optionalStringFromObject(object, key, error.OptionalFieldMustBeString) orelse return null;
+    return try allocator.dupe(u8, value);
+}
+
+pub fn requiredI32OrError(object: std.json.ObjectMap, key: []const u8, missing_error: anyerror) !i32 {
+    return try json_fields.requiredI32FromObject(object, key, missing_error, error.RequiredFieldMustBeInteger);
+}
+
+pub fn optionalU64(object: std.json.ObjectMap, key: []const u8, default_value: u64) !u64 {
+    return try json_fields.optionalU64FromObject(object, key, default_value, error.OptionalFieldMustBeInteger);
+}
+
+pub fn optionalBool(object: std.json.ObjectMap, key: []const u8, default_value: bool) !bool {
+    return try json_fields.optionalBoolFromObject(object, key, default_value, error.OptionalFieldMustBeBool);
+}
+
+pub fn parseSelectorField(allocator: std.mem.Allocator, object: std.json.ObjectMap) !selector.Selector {
+    const selector_value = object.get("selector") orelse return error.StepMissingSelector;
+    return try selector.parseFromJson(allocator, selector_value);
+}
+
+pub fn parseSelectorArrayField(allocator: std.mem.Allocator, object: std.json.ObjectMap) ![]selector.Selector {
+    const selectors_value = object.get("selectors") orelse return error.StepMissingSelectors;
+    if (selectors_value != .array) return error.SelectorsMustBeArray;
+    var selectors = std.ArrayList(selector.Selector).empty;
+    errdefer {
+        for (selectors.items) |wanted| wanted.deinit(allocator);
+        selectors.deinit(allocator);
+    }
+    for (selectors_value.array.items) |selector_value| {
+        try selectors.append(allocator, try selector.parseFromJson(allocator, selector_value));
+    }
+    if (selectors.items.len == 0) return error.SelectorsMustNotBeEmpty;
+    return try selectors.toOwnedSlice(allocator);
+}

package/src/schema_registry.zig

@@ -0,0 +1,53 @@
+const std = @import("std");
+const trace = @import("trace.zig");
+
+pub const PublicSchema = struct {
+    name: []const u8,
+    path: []const u8,
+    id: []const u8,
+    description: []const u8,
+};
+
+const public_schemas = [_]PublicSchema{
+    .{ .name = "json-rpc", .path = "schemas/json-rpc.schema.json", .id = "https://zmr.dev/schemas/json-rpc.schema.json", .description = "JSON-RPC requests and responses used by zmr serve" },
+    .{ .name = "scenario", .path = "schemas/scenario.schema.json", .id = "https://zmr.dev/schemas/scenario.schema.json", .description = "Scenario files consumed by zmr run and zmr validate" },
+    .{ .name = "snapshot", .path = "schemas/snapshot.schema.json", .id = "https://zmr.dev/schemas/snapshot.schema.json", .description = "ObservationSnapshot JSON emitted by live RPC and persisted trace snapshots" },
+    .{ .name = "semantic-snapshot", .path = "schemas/semantic-snapshot.schema.json", .id = "https://zmr.dev/schemas/semantic-snapshot.schema.json", .description = "Agent-optimized semantic snapshot emitted by observe.semanticSnapshot and zmr mcp" },
+    .{ .name = "action-result", .path = "schemas/action-result.schema.json", .id = "https://zmr.dev/schemas/action-result.schema.json", .description = "Typed action result shape reserved for richer protocol responses" },
+    .{ .name = "trace-event", .path = "schemas/trace-event.schema.json", .id = "https://zmr.dev/schemas/trace-event.schema.json", .description = "One JSONL event row from events.jsonl" },
+    .{ .name = "trace-manifest", .path = "schemas/trace-manifest.schema.json", .id = "https://zmr.dev/schemas/trace-manifest.schema.json", .description = "trace.json summary for one traced run" },
+    .{ .name = "zmr-config", .path = "schemas/zmr-config.schema.json", .id = "https://zmr.dev/schemas/zmr-config.schema.json", .description = "App-local .zmr/config.json defaults used by the CLI and npm wizard" },
+    .{ .name = "doctor-output", .path = "schemas/doctor-output.schema.json", .id = "https://zmr.dev/schemas/doctor-output.schema.json", .description = "Machine-readable zmr doctor --json setup diagnostics" },
+    .{ .name = "init-output", .path = "schemas/init-output.schema.json", .id = "https://zmr.dev/schemas/init-output.schema.json", .description = "Machine-readable zmr init --json bootstrap output" },
+    .{ .name = "import-output", .path = "schemas/import-output.schema.json", .id = "https://zmr.dev/schemas/import-output.schema.json", .description = "Machine-readable zmr import --json migration output" },
+    .{ .name = "devices-output", .path = "schemas/devices-output.schema.json", .id = "https://zmr.dev/schemas/devices-output.schema.json", .description = "Machine-readable zmr devices --json discovery output" },
+    .{ .name = "validate-output", .path = "schemas/validate-output.schema.json", .id = "https://zmr.dev/schemas/validate-output.schema.json", .description = "Machine-readable zmr validate --json scenario preflight output" },
+    .{ .name = "version-output", .path = "schemas/version-output.schema.json", .id = "https://zmr.dev/schemas/version-output.schema.json", .description = "Machine-readable zmr version --json compatibility output" },
+    .{ .name = "capabilities-output", .path = "schemas/capabilities-output.schema.json", .id = "https://zmr.dev/schemas/capabilities-output.schema.json", .description = "Machine-readable runner.capabilities JSON-RPC result" },
+    .{ .name = "explain-output", .path = "schemas/explain-output.schema.json", .id = "https://zmr.dev/schemas/explain-output.schema.json", .description = "Machine-readable zmr explain --json failure triage output" },
+    .{ .name = "run-output", .path = "schemas/run-output.schema.json", .id = "https://zmr.dev/schemas/run-output.schema.json", .description = "Machine-readable zmr run --json terminal summary output" },
+    .{ .name = "release-manifest", .path = "schemas/release-manifest.schema.json", .id = "https://zmr.dev/schemas/release-manifest.schema.json", .description = "Machine-readable RELEASE_MANIFEST.json emitted with release archives" },
+    .{ .name = "release-readiness-output", .path = "schemas/release-readiness-output.schema.json", .id = "https://zmr.dev/schemas/release-readiness-output.schema.json", .description = "Machine-readable zmr-release-readiness --json release evidence gate output" },
+    .{ .name = "schemas-output", .path = "schemas/schemas-output.schema.json", .id = "https://zmr.dev/schemas/schemas-output.schema.json", .description = "Machine-readable zmr schemas --json public schema index" },
+};
+
+pub fn all() []const PublicSchema {
+    return public_schemas[0..];
+}
+
+pub fn writeJson(writer: anytype) !void {
+    try writer.print("{{\"ok\":true,\"count\":{d},\"schemas\":[", .{public_schemas.len});
+    for (public_schemas, 0..) |schema_info, index| {
+        if (index > 0) try writer.writeAll(",");
+        try writer.writeAll("{\"name\":");
+        try trace.writeJsonString(writer, schema_info.name);
+        try writer.writeAll(",\"path\":");
+        try trace.writeJsonString(writer, schema_info.path);
+        try writer.writeAll(",\"id\":");
+        try trace.writeJsonString(writer, schema_info.id);
+        try writer.writeAll(",\"description\":");
+        try trace.writeJsonString(writer, schema_info.description);
+        try writer.writeAll("}");
+    }
+    try writer.writeAll("]}\n");
+}

package/src/selector.zig

@@ -0,0 +1,84 @@
+const std = @import("std");
+const types = @import("types.zig");
+
+pub const Selector = struct {
+    id: ?[]const u8 = null,
+    text: ?[]const u8 = null,
+    text_contains: ?[]const u8 = null,
+    content_desc: ?[]const u8 = null,
+    content_desc_contains: ?[]const u8 = null,
+    class_name: ?[]const u8 = null,
+
+    pub fn deinit(self: Selector, allocator: std.mem.Allocator) void {
+        if (self.id) |value| allocator.free(value);
+        if (self.text) |value| allocator.free(value);
+        if (self.text_contains) |value| allocator.free(value);
+        if (self.content_desc) |value| allocator.free(value);
+        if (self.content_desc_contains) |value| allocator.free(value);
+        if (self.class_name) |value| allocator.free(value);
+    }
+
+    pub fn clone(self: Selector, allocator: std.mem.Allocator) !Selector {
+        return .{
+            .id = try types.dupeOptional(allocator, self.id),
+            .text = try types.dupeOptional(allocator, self.text),
+            .text_contains = try types.dupeOptional(allocator, self.text_contains),
+            .content_desc = try types.dupeOptional(allocator, self.content_desc),
+            .content_desc_contains = try types.dupeOptional(allocator, self.content_desc_contains),
+            .class_name = try types.dupeOptional(allocator, self.class_name),
+        };
+    }
+};
+
+pub fn matches(node: types.UiNode, wanted: Selector) bool {
+    if (wanted.id) |id| {
+        if (node.resource_id == null or !std.mem.eql(u8, node.resource_id.?, id)) return false;
+    }
+    if (wanted.text) |text| {
+        if (node.text == null or !std.mem.eql(u8, node.text.?, text)) return false;
+    }
+    if (wanted.text_contains) |needle| {
+        if (node.text == null or std.mem.indexOf(u8, node.text.?, needle) == null) return false;
+    }
+    if (wanted.content_desc) |desc| {
+        if (node.content_desc == null or !std.mem.eql(u8, node.content_desc.?, desc)) return false;
+    }
+    if (wanted.content_desc_contains) |needle| {
+        if (node.content_desc == null or std.mem.indexOf(u8, node.content_desc.?, needle) == null) return false;
+    }
+    if (wanted.class_name) |class_name| {
+        if (!std.mem.eql(u8, node.class_name, class_name)) return false;
+    }
+    return node.visible;
+}
+
+pub fn find(nodes: []const types.UiNode, wanted: Selector) ?types.UiNode {
+    for (nodes) |node| {
+        if (matches(node, wanted)) return node;
+    }
+    return null;
+}
+
+pub fn parseFromJson(allocator: std.mem.Allocator, value: std.json.Value) !Selector {
+    if (value != .object) return error.SelectorMustBeObject;
+    const object = value.object;
+    const id = try stringField(allocator, object, "id") orelse try stringField(allocator, object, "resourceId");
+    return .{
+        .id = id,
+        .text = try stringField(allocator, object, "text"),
+        .text_contains = try stringField(allocator, object, "textContains"),
+        .content_desc = try stringField(allocator, object, "contentDesc"),
+        .content_desc_contains = try stringField(allocator, object, "contentDescContains"),
+        .class_name = try stringField(allocator, object, "className"),
+    };
+}
+
+fn stringField(
+    allocator: std.mem.Allocator,
+    object: std.json.ObjectMap,
+    key: []const u8,
+) !?[]const u8 {
+    const value = object.get(key) orelse return null;
+    if (value != .string) return error.SelectorFieldMustBeString;
+    return try allocator.dupe(u8, value.string);
+}