zeno-mobile-runner 0.2.16 → 0.2.17

package/src/main.zig

@@ -154,7 +154,7 @@ fn usage() !void {
         \\  zmr init --app [--dir <app-root>] [--app-id <id>] [--force] [--json]
         \\  zmr import flow-yaml <flow.yaml> --out <scenario.json> [--name <name>] [--app-id <id>] [--force] [--json]
         \\  zmr inspect [--json] [--dir <app-root>] [--config <path>]
-        \\  zmr run [scenario.json] [--json] [--config <path>] [--platform android|ios] [--ios-device-type simulator|physical] [--device <serial>] [--app-id <id>] [--trace-dir <path>] [--discover-out <scenario.json>] [--android-avd <name>] [--create-avd-if-missing] [--avd-system-image <pkg>] [--avd-device <profile>] [--restore-snapshot <name>] [--reset-emulator] [--wait-emulator] [--screen-record] [--no-screen-record] [--adb <path>] [--emulator <path>] [--avdmanager <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
+        \\  zmr run [scenario.json] [--json] [--config <path>] [--platform android|ios] [--ios-device-type simulator|physical] [--device <serial>] [--app-id <id>] [--trace-dir <path>] [--discover-out <scenario.json>] [--android-avd <name>] [--create-avd-if-missing] [--avd-system-image <pkg>] [--avd-device <profile>] [--restore-snapshot <name>] [--reset-emulator] [--wait-emulator] [--ensure-device] [--no-ensure-device] [--screen-record] [--no-screen-record] [--adb <path>] [--emulator <path>] [--avdmanager <path>] [--android-shim <path>] [--xcrun <path>] [--ios-shim <path>]
         \\  zmr report <trace-or-benchmark-dir> --out <report.html> [--junit <report.xml>]
         \\  zmr explain <trace-dir> [--json]
         \\  zmr export <trace-dir> --out <bundle.zmrtrace> [--redact] [--omit-screenshots]

package/src/mcp_protocol.zig

@@ -61,6 +61,9 @@ pub fn writeId(writer: anytype, id: ?std.json.Value) !void {
     }
 }
 
+const selector_schema_json =
+    "{\"type\":\"object\",\"additionalProperties\":false,\"minProperties\":1,\"properties\":{\"id\":{\"type\":\"string\"},\"resourceId\":{\"type\":\"string\"},\"stableId\":{\"type\":\"string\"},\"text\":{\"type\":\"string\"},\"textContains\":{\"type\":\"string\"},\"contentDesc\":{\"type\":\"string\"},\"contentDescContains\":{\"type\":\"string\"},\"className\":{\"type\":\"string\"}}}";
+
 const tool_list_json =
     "{\"tools\":[" ++
     "{\"name\":\"snapshot\",\"description\":\"Capture the current mobile observation snapshot as JSON.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
@@ -69,19 +72,19 @@ const tool_list_json =
     "{\"name\":\"launch_app\",\"description\":\"Launch the configured app on the selected device.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
     "{\"name\":\"stop_app\",\"description\":\"Stop the configured app on the selected device.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
     "{\"name\":\"clear_state\",\"description\":\"Clear the configured app state where the platform supports it.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
-    "{\"name\":\"tap\",\"description\":\"Tap a visible element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"}}}}," ++
-    "{\"name\":\"type\",\"description\":\"Type text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"text\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"text\":{\"type\":\"string\"}}}}," ++
+    "{\"name\":\"tap\",\"description\":\"Tap a visible element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ "}}}," ++
+    "{\"name\":\"type\",\"description\":\"Type text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"text\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"text\":{\"type\":\"string\"}}}}," ++
     "{\"name\":\"hide_keyboard\",\"description\":\"Dismiss the software keyboard when the platform can do so.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
-    "{\"name\":\"erase_text\",\"description\":\"Erase text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"selector\":{\"type\":\"object\"},\"maxChars\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"erase_text\",\"description\":\"Erase text, optionally after focusing an element by selector.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"maxChars\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
     "{\"name\":\"swipe\",\"description\":\"Swipe between absolute screen coordinates.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"x1\",\"y1\",\"x2\",\"y2\"],\"properties\":{\"x1\":{\"type\":\"integer\"},\"y1\":{\"type\":\"integer\"},\"x2\":{\"type\":\"integer\"},\"y2\":{\"type\":\"integer\"},\"durationMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
     "{\"name\":\"press_back\",\"description\":\"Press Android back or the platform-equivalent navigation action.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{}}}," ++
     "{\"name\":\"open_link\",\"description\":\"Open a deep link URL in the target app.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"url\"],\"properties\":{\"url\":{\"type\":\"string\"}}}}," ++
-    "{\"name\":\"wait_visible\",\"description\":\"Wait for an element selector to become visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"wait_not_visible\",\"description\":\"Wait for an element selector to no longer be visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"wait_any\",\"description\":\"Wait for the first visible selector from an ordered selector list.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selectors\"],\"properties\":{\"selectors\":{\"type\":\"array\",\"minItems\":1,\"items\":{\"type\":\"object\"}},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"scroll_until_visible\",\"description\":\"Scroll until an element selector is visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"direction\":{\"type\":\"string\",\"enum\":[\"down\",\"up\"]},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"assert_visible\",\"description\":\"Assert that an element selector is visible within the timeout.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
-    "{\"name\":\"assert_not_visible\",\"description\":\"Assert that an element selector is not visible within the timeout.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":{\"type\":\"object\"},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"wait_visible\",\"description\":\"Wait for an element selector to become visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"wait_not_visible\",\"description\":\"Wait for an element selector to no longer be visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"wait_any\",\"description\":\"Wait for the first visible selector from an ordered selector list.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selectors\"],\"properties\":{\"selectors\":{\"type\":\"array\",\"minItems\":1,\"items\":" ++ selector_schema_json ++ "},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"scroll_until_visible\",\"description\":\"Scroll until an element selector is visible.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"direction\":{\"type\":\"string\",\"enum\":[\"down\",\"up\"]},\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"assert_visible\",\"description\":\"Assert that an element selector is visible within the timeout.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
+    "{\"name\":\"assert_not_visible\",\"description\":\"Assert that an element selector is not visible within the timeout.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"selector\"],\"properties\":{\"selector\":" ++ selector_schema_json ++ ",\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
     "{\"name\":\"assert_healthy\",\"description\":\"Assert that the app is free of common crash and error overlays.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"timeoutMs\":{\"type\":\"integer\",\"minimum\":0}}}}," ++
     "{\"name\":\"scenario_validate\",\"description\":\"Validate a ZMR scenario file and return structured diagnostics.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"required\":[\"path\"],\"properties\":{\"path\":{\"type\":\"string\"}}}}," ++
     "{\"name\":\"trace_events\",\"description\":\"Read live trace events from a traced MCP session.\",\"inputSchema\":{\"type\":\"object\",\"additionalProperties\":false,\"properties\":{\"afterSeq\":{\"type\":\"integer\",\"minimum\":0},\"limit\":{\"type\":\"integer\",\"minimum\":1}}}}," ++

package/src/run_options.zig

@@ -28,6 +28,7 @@ pub const RawRunOptions = struct {
     android_avd_device_profile: ?[]const u8 = null,
     android_reset_before_run: ?bool = null,
     android_wait_ready: ?bool = null,
+    ensure_device: ?bool = null,
     platform: Platform = .android,
     ios_device_type: IosDeviceType = .simulator,
 };
@@ -46,6 +47,7 @@ pub const ResolvedRunOptions = struct {
     android_avd_device_profile: ?[]const u8,
     android_reset_before_run: bool,
     android_wait_ready: bool,
+    ensure_device: bool,
     platform: Platform,
     ios_device_type: IosDeviceType,
 };
@@ -86,6 +88,7 @@ pub fn resolveRun(raw: RawRunOptions, cfg: ?config.Config) ResolvedRunOptions {
         .android_avd_device_profile = raw.android_avd_device_profile orelse if (platform_cfg) |pc| pc.avd_device_profile else null,
         .android_reset_before_run = raw.android_reset_before_run orelse if (platform_cfg) |pc| pc.reset_before_run else false,
         .android_wait_ready = raw.android_wait_ready orelse if (platform_cfg) |pc| pc.wait_ready else false,
+        .ensure_device = raw.ensure_device orelse if (platform_cfg) |pc| pc.ensure_device else false,
         .platform = raw.platform,
         .ios_device_type = raw.ios_device_type,
     };
@@ -122,6 +125,7 @@ pub fn androidPreflight(
         .avd_device_profile = resolved.android_avd_device_profile,
         .reset_before_run = resolved.android_reset_before_run,
         .wait_ready = resolved.android_wait_ready,
+        .ensure_ready = resolved.ensure_device,
     };
     return if (android_emulator.hasWork(options)) options else null;
 }

package/src/scaffold.zig

@@ -131,13 +131,15 @@ fn writeAppConfig(path: []const u8, app_id: []const u8, force: bool) !void {
         \\    "enabled": true,
         \\    "defaultDevice": "emulator-5554",
         \\    "smokeScenario": ".zmr/android-smoke.json",
-        \\    "traceDir": "traces/zmr-android"
+        \\    "traceDir": "traces/zmr-android",
+        \\    "ensureDevice": true
         \\  },
         \\  "ios": {
         \\    "enabled": true,
         \\    "defaultDevice": "booted",
         \\    "smokeScenario": ".zmr/ios-smoke.json",
-        \\    "traceDir": "traces/zmr-ios"
+        \\    "traceDir": "traces/zmr-ios",
+        \\    "ensureDevice": true
         \\  },
         \\  "artifacts": {
         \\    "screenshots": true,
@@ -149,7 +151,7 @@ fn writeAppConfig(path: []const u8, app_id: []const u8, force: bool) !void {
         \\    "doctor": "zmr doctor --strict --json --config .zmr/config.json",
         \\    "schemas": "zmr schemas --json",
         \\    "validate": "zmr validate --json .zmr/android-smoke.json && zmr validate --json .zmr/ios-smoke.json",
-        \\    "android": "zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android",
+        \\    "android": "zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android --ensure-device",
         \\    "androidReport": "zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml",
         \\    "androidReliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id
     );
@@ -157,7 +159,7 @@ fn writeAppConfig(path: []const u8, app_id: []const u8, force: bool) !void {
     try writeJsonShellArg(writer, app_id);
     try writer.writeAll(
         \\ --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && \"$ZMR_BIN\" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml",
-        \\    "ios": "zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios",
+        \\    "ios": "zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios --ensure-device",
         \\    "iosReport": "zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml",
         \\    "iosReliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id
     );
@@ -366,7 +368,7 @@ fn writeAgentInstructions(path: []const u8, app_id: []const u8, force: bool) !vo
         \\## Direct Smoke Runs
         \\
         \\```bash
-        \\zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android
+        \\zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android --ensure-device
         \\zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml
         \\export ZMR_BIN="${ZMR_BIN:-zmr}"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id
     );
@@ -374,7 +376,7 @@ fn writeAgentInstructions(path: []const u8, app_id: []const u8, force: bool) !vo
     try writeShellArg(writer, app_id);
     try writer.writeAll(
         \\ --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && "$ZMR_BIN" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml
-        \\zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios
+        \\zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios --ensure-device
         \\zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml
         \\export ZMR_BIN="${ZMR_BIN:-zmr}"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id
     );
@@ -399,7 +401,7 @@ fn writeAgentInstructions(path: []const u8, app_id: []const u8, force: bool) !vo
         \\zmr doctor --strict --json --config .zmr/config.json
         \\zmr schemas --json
         \\zmr validate --json .zmr/android-smoke.json && zmr validate --json .zmr/ios-smoke.json
-        \\zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android
+        \\zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android --ensure-device
         \\zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml
         \\export ZMR_BIN="${ZMR_BIN:-zmr}"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id
     );
@@ -407,7 +409,7 @@ fn writeAgentInstructions(path: []const u8, app_id: []const u8, force: bool) !vo
     try writeShellArg(writer, app_id);
     try writer.writeAll(
         \\ --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && "$ZMR_BIN" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml
-        \\zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios
+        \\zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios --ensure-device
         \\zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml
         \\export ZMR_BIN="${ZMR_BIN:-zmr}"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id
     );

package/src/scenario.zig

@@ -179,6 +179,7 @@ pub fn parseSlice(allocator: std.mem.Allocator, content: []const u8) !Scenario {
     defer parsed.deinit();
     if (parsed.value != .object) return error.ScenarioMustBeObject;
     const root = parsed.value.object;
+    try rejectUnknownRootFields(root);
 
     const name = try fields.requiredString(allocator, root, "name");
     errdefer allocator.free(name);
@@ -204,6 +205,7 @@ pub fn parseSlice(allocator: std.mem.Allocator, content: []const u8) !Scenario {
 fn parseStep(allocator: std.mem.Allocator, value: std.json.Value) anyerror!Step {
     if (value != .object) return error.StepMustBeObject;
     const object = value.object;
+    try rejectUnknownStepFields(object);
     var parsed = try parseRawStep(allocator, object);
     errdefer parsed.deinit(allocator);
 
@@ -352,6 +354,47 @@ fn parseRawStep(allocator: std.mem.Allocator, object: std.json.ObjectMap) anyerr
     return error.unknownScenarioAction;
 }
 
+fn rejectUnknownRootFields(object: std.json.ObjectMap) !void {
+    var iterator = object.iterator();
+    while (iterator.next()) |entry| {
+        const key = entry.key_ptr.*;
+        if (std.mem.eql(u8, key, "name") or
+            std.mem.eql(u8, key, "appId") or
+            std.mem.eql(u8, key, "steps")) continue;
+        return error.UnknownScenarioField;
+    }
+}
+
+fn rejectUnknownStepFields(object: std.json.ObjectMap) !void {
+    var iterator = object.iterator();
+    while (iterator.next()) |entry| {
+        if (!isKnownStepField(entry.key_ptr.*)) return error.UnknownScenarioStepField;
+    }
+}
+
+fn isKnownStepField(key: []const u8) bool {
+    return std.mem.eql(u8, key, "action") or
+        std.mem.eql(u8, key, "optional") or
+        std.mem.eql(u8, key, "url") or
+        std.mem.eql(u8, key, "latitude") or
+        std.mem.eql(u8, key, "longitude") or
+        std.mem.eql(u8, key, "selector") or
+        std.mem.eql(u8, key, "selectors") or
+        std.mem.eql(u8, key, "text") or
+        std.mem.eql(u8, key, "maxChars") or
+        std.mem.eql(u8, key, "x1") or
+        std.mem.eql(u8, key, "y1") or
+        std.mem.eql(u8, key, "x2") or
+        std.mem.eql(u8, key, "y2") or
+        std.mem.eql(u8, key, "durationMs") or
+        std.mem.eql(u8, key, "timeoutMs") or
+        std.mem.eql(u8, key, "direction") or
+        std.mem.eql(u8, key, "times") or
+        std.mem.eql(u8, key, "steps") or
+        std.mem.eql(u8, key, "step") or
+        std.mem.eql(u8, key, "ms");
+}
+
 fn parseLatitude(object: std.json.ObjectMap) !f64 {
     const latitude = try fields.requiredF64OrError(object, "latitude", error.StepMissingLatitude, error.StepLatitudeMustBeNumber);
     if (latitude < -90.0 or latitude > 90.0) return error.StepLatitudeOutOfRange;

package/src/selector.zig

@@ -3,6 +3,7 @@ const types = @import("types.zig");
 
 pub const Selector = struct {
     id: ?[]const u8 = null,
+    stable_id: ?[]const u8 = null,
     text: ?[]const u8 = null,
     text_contains: ?[]const u8 = null,
     content_desc: ?[]const u8 = null,
@@ -11,6 +12,7 @@ pub const Selector = struct {
 
     pub fn deinit(self: Selector, allocator: std.mem.Allocator) void {
         if (self.id) |value| allocator.free(value);
+        if (self.stable_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);
@@ -21,6 +23,7 @@ pub const Selector = struct {
     pub fn clone(self: Selector, allocator: std.mem.Allocator) !Selector {
         return .{
             .id = try types.dupeOptional(allocator, self.id),
+            .stable_id = try types.dupeOptional(allocator, self.stable_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),
@@ -28,12 +31,26 @@ pub const Selector = struct {
             .class_name = try types.dupeOptional(allocator, self.class_name),
         };
     }
+
+    pub fn hasAny(self: Selector) bool {
+        return self.id != null or
+            self.stable_id != null or
+            self.text != null or
+            self.text_contains != null or
+            self.content_desc != null or
+            self.content_desc_contains != null or
+            self.class_name != null;
+    }
 };
 
 pub fn matches(node: types.UiNode, wanted: Selector) bool {
+    if (!wanted.hasAny()) return false;
     if (wanted.id) |id| {
         if (node.resource_id == null or !std.mem.eql(u8, node.resource_id.?, id)) return false;
     }
+    if (wanted.stable_id) |stable_id| {
+        if (!std.mem.eql(u8, node.stable_id, stable_id)) return false;
+    }
     if (wanted.text) |text| {
         if (node.text == null or !std.mem.eql(u8, node.text.?, text)) return false;
     }
@@ -62,15 +79,42 @@ pub fn find(nodes: []const types.UiNode, wanted: Selector) ?types.UiNode {
 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"),
-    };
+    try rejectUnknownFields(object);
+    var parsed: Selector = .{};
+    errdefer parsed.deinit(allocator);
+    parsed.id = try stringField(allocator, object, "id");
+    const resource_id = try stringField(allocator, object, "resourceId");
+    if (parsed.id == null) {
+        parsed.id = resource_id;
+    } else if (resource_id) |resource_id_value| {
+        allocator.free(resource_id_value);
+    }
+    parsed.stable_id = try stringField(allocator, object, "stableId");
+    parsed.text = try stringField(allocator, object, "text");
+    parsed.text_contains = try stringField(allocator, object, "textContains");
+    parsed.content_desc = try stringField(allocator, object, "contentDesc");
+    parsed.content_desc_contains = try stringField(allocator, object, "contentDescContains");
+    parsed.class_name = try stringField(allocator, object, "className");
+    if (!parsed.hasAny()) return error.SelectorMustNotBeEmpty;
+    return parsed;
+}
+
+fn rejectUnknownFields(object: std.json.ObjectMap) !void {
+    var iterator = object.iterator();
+    while (iterator.next()) |entry| {
+        if (!isKnownField(entry.key_ptr.*)) return error.UnknownSelectorField;
+    }
+}
+
+fn isKnownField(key: []const u8) bool {
+    return std.mem.eql(u8, key, "id") or
+        std.mem.eql(u8, key, "resourceId") or
+        std.mem.eql(u8, key, "stableId") or
+        std.mem.eql(u8, key, "text") or
+        std.mem.eql(u8, key, "textContains") or
+        std.mem.eql(u8, key, "contentDesc") or
+        std.mem.eql(u8, key, "contentDescContains") or
+        std.mem.eql(u8, key, "className");
 }
 
 fn stringField(

package/src/trace_json.zig

@@ -109,6 +109,10 @@ pub fn writeSelectorJson(writer: anytype, wanted: selector.Selector) !void {
         try jsonField(writer, "id", value, first);
         first = false;
     }
+    if (wanted.stable_id) |value| {
+        try jsonField(writer, "stableId", value, first);
+        first = false;
+    }
     if (wanted.text) |value| {
         try jsonField(writer, "text", value, first);
         first = false;

package/src/validation.zig

@@ -87,9 +87,13 @@ fn diagnoseFailure(allocator: std.mem.Allocator, content: []const u8, err: anyer
     if (syntaxLocation(allocator, content)) |location| return location;
     return switch (err) {
         error.ScenarioMustBeObject => try pathDiagnostic(allocator, content, "$", null),
+        error.UnknownScenarioField,
+        => try pathDiagnostic(allocator, content, "$", null),
         error.ScenarioMissingSteps,
         error.ScenarioStepsMustBeArray,
         => try pathDiagnostic(allocator, content, "$.steps", "steps"),
+        error.UnknownScenarioStepField,
+        => try pathDiagnostic(allocator, content, "$.steps[]", null),
         error.StepMissingAction,
         error.StepActionMustBeString,
         error.unknownAction,
@@ -120,6 +124,7 @@ fn diagnoseFailure(allocator: std.mem.Allocator, content: []const u8, err: anyer
         error.MissingSelector,
         error.StepMissingSelector,
         error.SelectorMustNotBeEmpty,
+        error.UnknownSelectorField,
         => try pathDiagnostic(allocator, content, "$.steps[].selector", "selector"),
         error.MissingSelectors,
         error.StepMissingSelectors,

package/src/version.zig

@@ -1,4 +1,4 @@
-pub const runner_version = "0.2.16";
+pub const runner_version = "0.2.17";
 pub const protocol_version = "2026-04-28";
 pub const protocol_min_compatible_version = "2026-04-28";
 pub const protocol_stability = "dev-preview";