zeno-mobile-runner 0.1.8 → 0.2.0

package/scripts/demo.sh

@@ -37,9 +37,12 @@ echo "== Validate demo scenarios =="
 ./zig-out/bin/zmr validate examples/android-app-referral-deep-link.json
 ./zig-out/bin/zmr validate examples/android-app-error-state.json
 ./zig-out/bin/zmr validate examples/android-shim-smoke.json
+./zig-out/bin/zmr validate examples/android-workflow.json
+./zig-out/bin/zmr validate examples/react-native-expo-workflow.json
 ./zig-out/bin/zmr validate examples/ios-smoke.json
 ./zig-out/bin/zmr validate examples/ios-dev-client-open-link.json
 ./zig-out/bin/zmr validate examples/ios-shim-smoke.json
+./zig-out/bin/zmr validate examples/ios-shim-workflow.json
 
 echo
 echo "== Validate diagnostics: field and line location =="

package/scripts/install-ios-shim.sh

@@ -342,14 +342,14 @@ is_server_running() {
     return 1
   fi
   command="\$(ps -p "\$pid" -o command= 2>/dev/null || true)"
-  [[ "\$command" == *xcodebuild* && "\$command" == *ZMRShimUITests* ]]
+  [[ "\$command" == *xcodebuild* && "\$command" == *"$TEST_TARGET"* ]]
 }
 
 run_oneshot() {
   local request_file response_file oneshot_log destination_id
   request_file="\$(mktemp "\$STATE_DIR/request.XXXXXX")"
   response_file="\$(mktemp "\$STATE_DIR/response.XXXXXX")"
-  oneshot_log="\$(mktemp "\$STATE_DIR/xcodebuild.oneshot.XXXXXX.log")"
+  oneshot_log="\$(mktemp "\$STATE_DIR/xcodebuild.oneshot.log.XXXXXX")"
   cp "\$STDIN_FILE" "\$request_file"
   destination_id="\$(destination_spec)"
 

package/shims/ios/ZMRShim.swift

@@ -22,6 +22,11 @@ struct ZMRShimBounds: Encodable {
     let height: Int
 }
 
+struct ZMRShimViewport: Encodable {
+    let width: Int
+    let height: Int
+}
+
 struct ZMRShimNode: Encodable {
     let id: String
     let type: String
@@ -35,6 +40,11 @@ struct ZMRShimNode: Encodable {
 }
 
 enum ZMRShim {
+    static func viewport(app: XCUIApplication) -> ZMRShimViewport {
+        let frame = app.frame
+        return ZMRShimViewport(width: Int(frame.size.width), height: Int(frame.size.height))
+    }
+
     static func snapshot(app: XCUIApplication) -> [ZMRShimNode] {
         let queries: [(XCUIElement.ElementType, XCUIElementQuery)] = [
             (.button, app.buttons),

package/shims/ios/ZMRShimUITestCase.swift

@@ -105,10 +105,15 @@ final class ZMRShimUITestCase: XCTestCase {
     }
 
     private func run(command: ZMRShimCommand, app: XCUIApplication) -> [String: Any] {
+        if commandRequiresForeground(command), let foregroundError = ensureAppForeground(app: app) {
+            return foregroundError
+        }
+
         switch command.cmd {
         case "snapshot":
             return [
                 "status": "ok",
+                "viewport": ZMRShim.viewport(app: app).json,
                 "nodes": ZMRShim.snapshot(app: app).map { $0.json }
             ]
         case "screenshot":
@@ -188,6 +193,34 @@ final class ZMRShimUITestCase: XCTestCase {
         }
     }
 
+    private func commandRequiresForeground(_ command: ZMRShimCommand) -> Bool {
+        switch command.cmd {
+        case "snapshot", "query", "tap", "type", "eraseText", "hideKeyboard", "swipe", "settle":
+            return true
+        default:
+            return false
+        }
+    }
+
+    private func ensureAppForeground(app: XCUIApplication) -> [String: Any]? {
+        if app.state != .runningForeground {
+            app.activate()
+        }
+
+        let deadline = Date().addingTimeInterval(5)
+        while Date() < deadline {
+            if app.state == .runningForeground {
+                return nil
+            }
+            Thread.sleep(forTimeInterval: 0.1)
+        }
+
+        return error(
+            "app.not_foreground",
+            "target app did not become foreground; state=\(app.state.rawValue)"
+        )
+    }
+
     private func ok() -> [String: Any] {
         ["status": "ok"]
     }
@@ -532,6 +565,15 @@ private extension ZMRShimBounds {
     }
 }
 
+private extension ZMRShimViewport {
+    var json: [String: Any] {
+        [
+            "width": width,
+            "height": height
+        ]
+    }
+}
+
 private extension ZMRShimNode {
     var json: [String: Any] {
         [

package/shims/ios/protocol.md

@@ -51,6 +51,7 @@ turn every snapshot into a full hierarchy crawl:
 ```json
 {
   "status": "ok",
+  "viewport": { "width": 390, "height": 844 },
   "nodes": [
     {
       "id": "button-continue",

package/src/cli_import.zig

@@ -14,36 +14,52 @@ pub const ParsedArgs = struct {
 };
 
 pub fn parseArgs(args: []const []const u8) !ParsedArgs {
-    if (args.len == 0) return error.MissingImportFormat;
-    if (args.len == 1) return error.MissingImportPath;
+    var format: ?[]const u8 = null;
+    var source_path: ?[]const u8 = null;
+    var out_path: ?[]const u8 = null;
+    var name: ?[]const u8 = null;
+    var app_id: ?[]const u8 = null;
+    var force = false;
+    var json = false;
 
-    var parsed = ParsedArgs{
-        .format = args[0],
-        .source_path = args[1],
-    };
-
-    var index: usize = 2;
+    var index: usize = 0;
     while (index < args.len) : (index += 1) {
         const arg = args[index];
         if (std.mem.eql(u8, arg, "--out")) {
             index += 1;
-            parsed.out_path = if (index < args.len) args[index] else return error.MissingImportOut;
+            out_path = if (index < args.len) args[index] else return error.MissingImportOut;
         } else if (std.mem.eql(u8, arg, "--name")) {
             index += 1;
-            parsed.name = if (index < args.len) args[index] else return error.MissingImportName;
+            name = if (index < args.len) args[index] else return error.MissingImportName;
         } else if (std.mem.eql(u8, arg, "--app-id")) {
             index += 1;
-            parsed.app_id = if (index < args.len) args[index] else return error.MissingAppId;
+            app_id = if (index < args.len) args[index] else return error.MissingAppId;
         } else if (std.mem.eql(u8, arg, "--force")) {
-            parsed.force = true;
+            force = true;
         } else if (std.mem.eql(u8, arg, "--json")) {
-            parsed.json = true;
+            json = true;
+        } else if (std.mem.startsWith(u8, arg, "--")) {
+            return error.UnknownFlag;
+        } else if (format == null) {
+            format = arg;
+        } else if (source_path == null) {
+            source_path = arg;
         } else {
             return error.UnknownFlag;
         }
     }
-    if (parsed.out_path == null) return error.MissingImportOut;
-    return parsed;
+    if (format == null) return error.MissingImportFormat;
+    if (source_path == null) return error.MissingImportPath;
+    if (out_path == null) return error.MissingImportOut;
+    return ParsedArgs{
+        .format = format.?,
+        .source_path = source_path.?,
+        .out_path = out_path,
+        .name = name,
+        .app_id = app_id,
+        .force = force,
+        .json = json,
+    };
 }
 
 pub fn run(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {

package/src/cli_trace.zig

@@ -22,24 +22,34 @@ pub const ExportArgs = struct {
 };
 
 pub fn parseReportArgs(args: []const []const u8) !ReportArgs {
-    if (args.len == 0) return error.MissingReportInput;
-    var parsed = ReportArgs{ .input_path = args[0] };
+    var input_path: ?[]const u8 = null;
+    var out_path: ?[]const u8 = null;
+    var junit_path: ?[]const u8 = null;
 
-    var index: usize = 1;
+    var index: usize = 0;
     while (index < args.len) : (index += 1) {
         const arg = args[index];
         if (std.mem.eql(u8, arg, "--out")) {
             index += 1;
-            parsed.out_path = if (index < args.len) args[index] else return error.MissingReportOutput;
+            out_path = if (index < args.len) args[index] else return error.MissingReportOutput;
         } else if (std.mem.eql(u8, arg, "--junit")) {
             index += 1;
-            parsed.junit_path = if (index < args.len) args[index] else return error.MissingJUnitOutput;
+            junit_path = if (index < args.len) args[index] else return error.MissingJUnitOutput;
+        } else if (std.mem.startsWith(u8, arg, "--")) {
+            return error.UnknownFlag;
+        } else if (input_path == null) {
+            input_path = arg;
         } else {
             return error.UnknownFlag;
         }
     }
-    if (parsed.out_path == null) return error.MissingReportOutput;
-    return parsed;
+    if (input_path == null) return error.MissingReportInput;
+    if (out_path == null) return error.MissingReportOutput;
+    return ReportArgs{
+        .input_path = input_path.?,
+        .out_path = out_path,
+        .junit_path = junit_path,
+    };
 }
 
 pub fn parseExplainArgs(args: []const []const u8) !ExplainArgs {
@@ -58,26 +68,38 @@ pub fn parseExplainArgs(args: []const []const u8) !ExplainArgs {
 }
 
 pub fn parseExportArgs(args: []const []const u8) !ExportArgs {
-    if (args.len == 0) return error.MissingTraceDir;
-    var parsed = ExportArgs{ .trace_dir = args[0] };
+    var trace_dir: ?[]const u8 = null;
+    var out_path: ?[]const u8 = null;
+    var redact = false;
+    var omit_screenshots = false;
 
-    var index: usize = 1;
+    var index: usize = 0;
     while (index < args.len) : (index += 1) {
         const arg = args[index];
         if (std.mem.eql(u8, arg, "--out")) {
             index += 1;
-            parsed.out_path = if (index < args.len) args[index] else return error.MissingTraceBundleOutput;
+            out_path = if (index < args.len) args[index] else return error.MissingTraceBundleOutput;
         } else if (std.mem.eql(u8, arg, "--redact")) {
-            parsed.redact = true;
+            redact = true;
         } else if (std.mem.eql(u8, arg, "--omit-screenshots")) {
-            parsed.redact = true;
-            parsed.omit_screenshots = true;
+            redact = true;
+            omit_screenshots = true;
+        } else if (std.mem.startsWith(u8, arg, "--")) {
+            return error.UnknownFlag;
+        } else if (trace_dir == null) {
+            trace_dir = arg;
         } else {
             return error.UnknownFlag;
         }
     }
-    if (parsed.out_path == null) return error.MissingTraceBundleOutput;
-    return parsed;
+    if (trace_dir == null) return error.MissingTraceDir;
+    if (out_path == null) return error.MissingTraceBundleOutput;
+    return ExportArgs{
+        .trace_dir = trace_dir.?,
+        .out_path = out_path,
+        .redact = redact,
+        .omit_screenshots = omit_screenshots,
+    };
 }
 
 pub fn runReport(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {

package/src/cli_validate.zig

@@ -9,17 +9,23 @@ pub const ParsedArgs = struct {
 };
 
 pub fn parseArgs(args: []const []const u8) !ParsedArgs {
-    if (args.len == 0) return error.MissingScenarioPath;
-
-    var parsed = ParsedArgs{ .path = args[0] };
-    for (args[1..]) |arg| {
+    var path: ?[]const u8 = null;
+    var json = false;
+    for (args) |arg| {
         if (std.mem.eql(u8, arg, "--json")) {
-            parsed.json = true;
+            json = true;
+        } else if (std.mem.startsWith(u8, arg, "--")) {
+            return error.UnknownFlag;
+        } else if (path == null) {
+            path = arg;
         } else {
             return error.UnknownFlag;
         }
     }
-    return parsed;
+    return ParsedArgs{
+        .path = path orelse return error.MissingScenarioPath,
+        .json = json,
+    };
 }
 
 pub fn run(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {

package/src/ios.zig

@@ -10,8 +10,10 @@ const types = @import("types.zig");
 
 const default_max_output = 32 * 1024 * 1024;
 // Clean iOS prebuilds can force the XCTest shim script through a full native
-// dependency build before it can answer the first selector query.
-const shim_timeout_ms = 5_400_000;
+// dependency build before it can answer the first selector query. Slower CI
+// hardware can override the default with ZMR_IOS_SHIM_TIMEOUT_MS.
+const default_shim_timeout_ms = 5_400_000;
+const shim_timeout_env = "ZMR_IOS_SHIM_TIMEOUT_MS";
 const shim_best_effort_timeout_ms = 10_000;
 const shim_command_attempts = 2;
 const shim_bootstrap_retry_delay_ms = 500;
@@ -126,7 +128,9 @@ pub const IosDevice = struct {
         const result = try self.runSimctl(&.{ "openurl", self.target(), url }, default_max_output);
         defer result.deinit(self.allocator);
         try result.ensureSuccess();
-        self.acceptOpenURLConfirmationBestEffort();
+        if (urlMayNeedOpenConfirmation(url)) {
+            self.acceptOpenURLConfirmationBestEffort();
+        }
     }
 
     pub fn tap(self: *IosDevice, x: i32, y: i32) !void {
@@ -212,15 +216,22 @@ pub const IosDevice = struct {
 
         const active_package = try self.allocator.dupe(u8, self.app_id);
         errdefer self.allocator.free(active_package);
-        const nodes = if (self.shim_path != null)
-            self.snapshotNodesFromShim() catch |err| blk: {
+        var shim_viewport: ?types.Viewport = null;
+        const nodes = if (self.shim_path != null) blk: {
+            const shim_snapshot = self.snapshotFromShim() catch |err| {
                 if (screenshot_artifact == null) return err;
                 if (writer) |tw| try self.recordSnapshotSemanticFailure(tw, screenshot_artifact.?, err);
                 break :blk try self.allocator.alloc(types.UiNode, 0);
-            }
-        else
-            try self.allocator.alloc(types.UiNode, 0);
+            };
+            shim_viewport = shim_snapshot.viewport;
+            break :blk shim_snapshot.nodes;
+        } else try self.allocator.alloc(types.UiNode, 0);
         errdefer self.allocator.free(nodes);
+        if (shim_viewport) |value| {
+            if (value.width > 0 and value.height > 0) {
+                viewport = value;
+            }
+        }
 
         return .{
             .id = id,
@@ -260,10 +271,10 @@ pub const IosDevice = struct {
         return try self.allocator.dupe(u8, result.stdout);
     }
 
-    fn snapshotNodesFromShim(self: *IosDevice) ![]types.UiNode {
+    fn snapshotFromShim(self: *IosDevice) !ios_shim.SnapshotResponse {
         const response = try self.runShim(.{ .kind = .snapshot });
         defer self.allocator.free(response);
-        return try ios_shim.parseSnapshotNodes(self.allocator, response);
+        return try ios_shim.parseSnapshotResponse(self.allocator, response);
     }
 
     fn recordSnapshotSemanticFailure(self: *IosDevice, writer: *trace.TraceWriter, screenshot_artifact: []const u8, err: anyerror) !void {
@@ -319,7 +330,7 @@ pub const IosDevice = struct {
     }
 
     fn runShim(self: *IosDevice, shim_command: ios_shim.Command) ![]u8 {
-        return self.runShimWithTimeout(shim_command, shim_timeout_ms);
+        return self.runShimWithTimeout(shim_command, shimTimeoutMs());
     }
 
     fn runShimWithTimeout(self: *IosDevice, shim_command: ios_shim.Command, timeout_ms: u64) ![]u8 {
@@ -384,6 +395,25 @@ fn isTransientShimBootstrapFailure(result: command.ExecResult) bool {
         std.mem.indexOf(u8, result.stderr, "operation never finished bootstrapping") != null;
 }
 
+fn shimTimeoutMs() u64 {
+    return parseShimTimeoutMs(std.posix.getenv(shim_timeout_env));
+}
+
+fn parseShimTimeoutMs(raw: ?[]const u8) u64 {
+    const value = raw orelse return default_shim_timeout_ms;
+    const parsed = std.fmt.parseInt(u64, value, 10) catch return default_shim_timeout_ms;
+    if (parsed == 0) return default_shim_timeout_ms;
+    return parsed;
+}
+
+fn urlMayNeedOpenConfirmation(url: []const u8) bool {
+    return startsWithIgnoreCase(url, "http://") or startsWithIgnoreCase(url, "https://");
+}
+
+fn startsWithIgnoreCase(value: []const u8, prefix: []const u8) bool {
+    return value.len >= prefix.len and std.ascii.eqlIgnoreCase(value[0..prefix.len], prefix);
+}
+
 pub fn listDevices(allocator: std.mem.Allocator, xcrun_path: []const u8) ![]types.DeviceInfo {
     return try ios_devices.listSimulators(allocator, xcrun_path);
 }
@@ -401,6 +431,13 @@ pub fn parsePhysicalDevicesJson(allocator: std.mem.Allocator, content: []const u
 }
 
 test "ios xctest shim timeout allows cold xcodebuild startup" {
-    try std.testing.expect(shim_timeout_ms >= 5_400_000);
+    try std.testing.expect(default_shim_timeout_ms >= 5_400_000);
     try std.testing.expect(shim_best_effort_timeout_ms <= 15_000);
 }
+
+test "ios xctest shim timeout env override" {
+    try std.testing.expectEqual(@as(u64, default_shim_timeout_ms), parseShimTimeoutMs(null));
+    try std.testing.expectEqual(@as(u64, 600_000), parseShimTimeoutMs("600000"));
+    try std.testing.expectEqual(@as(u64, default_shim_timeout_ms), parseShimTimeoutMs("not-a-number"));
+    try std.testing.expectEqual(@as(u64, default_shim_timeout_ms), parseShimTimeoutMs("0"));
+}

package/src/ios_shim.zig

@@ -32,6 +32,16 @@ pub const Command = struct {
     max_chars: ?u32 = null,
 };
 
+pub const SnapshotResponse = struct {
+    nodes: []types.UiNode,
+    viewport: types.Viewport = .{},
+
+    pub fn deinit(self: SnapshotResponse, allocator: std.mem.Allocator) void {
+        for (self.nodes) |node| node.deinit(allocator);
+        allocator.free(self.nodes);
+    }
+};
+
 pub fn writeCommandJson(writer: anytype, command: Command) !void {
     try writer.writeAll("{\"cmd\":");
     try trace.writeJsonString(writer, commandName(command.kind));
@@ -54,12 +64,13 @@ pub fn writeCommandJson(writer: anytype, command: Command) !void {
     try writer.writeAll("}\n");
 }
 
-pub fn parseSnapshotNodes(allocator: std.mem.Allocator, content: []const u8) ![]types.UiNode {
+pub fn parseSnapshotResponse(allocator: std.mem.Allocator, content: []const u8) !SnapshotResponse {
     const parsed = try std.json.parseFromSlice(std.json.Value, allocator, content, .{});
     defer parsed.deinit();
     if (parsed.value != .object) return error.IosShimResponseMustBeObject;
     const status = fieldString(parsed.value.object, "status") orelse return error.IosShimMissingStatus;
     if (!std.mem.eql(u8, status, "ok")) return error.IosShimResponseNotOk;
+    const viewport = parseViewport(parsed.value.object.get("viewport"));
     const nodes_value = parsed.value.object.get("nodes") orelse return error.IosShimMissingNodes;
     if (nodes_value != .array) return error.IosShimNodesMustBeArray;
 
@@ -97,7 +108,15 @@ pub fn parseSnapshotNodes(allocator: std.mem.Allocator, content: []const u8) ![]
         });
     }
 
-    return try nodes.toOwnedSlice(allocator);
+    return .{
+        .nodes = try nodes.toOwnedSlice(allocator),
+        .viewport = viewport,
+    };
+}
+
+pub fn parseSnapshotNodes(allocator: std.mem.Allocator, content: []const u8) ![]types.UiNode {
+    const snapshot = try parseSnapshotResponse(allocator, content);
+    return snapshot.nodes;
 }
 
 pub fn parseOkResponse(content: []const u8) !void {
@@ -278,6 +297,21 @@ fn intField(object: std.json.ObjectMap, key: []const u8) !i32 {
     return @intCast(value.integer);
 }
 
+fn parseViewport(value: ?std.json.Value) types.Viewport {
+    const actual = value orelse return .{};
+    if (actual != .object) return .{};
+    const width = optionalU32Field(actual.object, "width") orelse return .{};
+    const height = optionalU32Field(actual.object, "height") orelse return .{};
+    return .{ .width = width, .height = height };
+}
+
+fn optionalU32Field(object: std.json.ObjectMap, key: []const u8) ?u32 {
+    const value = object.get(key) orelse return null;
+    if (value != .integer) return null;
+    if (value.integer < 0 or value.integer > std.math.maxInt(u32)) return null;
+    return @intCast(value.integer);
+}
+
 fn dupeOptional(allocator: std.mem.Allocator, value: ?[]const u8) !?[]const u8 {
     if (value) |actual| return try allocator.dupe(u8, actual);
     return null;

package/src/main.zig

@@ -88,6 +88,9 @@ fn writeTopLevelError(err: anyerror) void {
     if (err == error.CommandFailed) {
         stderr.writeAll("hint: run `zmr doctor --json` for setup diagnostics.\n") catch {};
     }
+    if (err == error.UnknownFlag) {
+        stderr.writeAll("hint: run `zmr help` for each command's flags and arguments.\n") catch {};
+    }
 }
 
 fn exitCodeForError(err: anyerror) u8 {

package/src/version.zig

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

package/viewer/app.js

@@ -73,22 +73,42 @@ els.dropTarget.addEventListener("drop", async (event) => {
 });
 
 async function loadBundleFile(file) {
-  setStatus(`Loading ${file.name}`);
+  await loadBundle(file.name, () => file.arrayBuffer());
+}
+
+async function loadBundleFromUrl(url) {
+  const name = url.split("/").pop() || url;
+  await loadBundle(name, async () => {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch ${url}: HTTP ${response.status}`);
+    }
+    return await response.arrayBuffer();
+  });
+}
+
+async function loadBundle(name, getBuffer) {
+  setStatus(`Loading ${name}`);
   try {
     stopReplay();
     revokeObjectUrls();
-    const entries = parseTarArchive(await file.arrayBuffer());
+    const entries = parseTarArchive(await getBuffer());
     const model = buildTraceModel(entries);
     state.model = model;
     state.selectedFrameIndex = 0;
     state.selectedEvent = model.replayFrames[0]?.event ?? model.events[0] ?? null;
-    renderModel(file.name);
+    renderModel(name);
   } catch (error) {
     console.error(error);
     setStatus(error instanceof Error ? error.message : String(error), true);
   }
 }
 
+const bundleParam = new URLSearchParams(window.location.search).get("bundle");
+if (bundleParam) {
+  loadBundleFromUrl(bundleParam);
+}
+
 function renderModel(fileName) {
   const { summary } = state.model;
   els.emptyState.classList.add("hidden");