zig-mobile-runner 0.1.0

package/shims/ios/protocol.md

@@ -0,0 +1,74 @@
+# iOS Shim Protocol
+
+The iOS shim protocol is internal and may change before `v1.0.0`.
+
+Commands are newline-delimited JSON objects:
+
+```json
+{"cmd":"snapshot"}
+{"cmd":"tap","selector":"text=Continue","x":20,"y":40}
+{"cmd":"type","selector":"identifier=email","text":"hello"}
+{"cmd":"eraseText","selector":"identifier=email","maxChars":20}
+{"cmd":"hideKeyboard"}
+{"cmd":"swipe","x1":300,"y1":900,"x2":300,"y2":300,"durationMs":250}
+{"cmd":"pressBack"}
+{"cmd":"settle","durationMs":1000}
+{"cmd":"appState"}
+{"cmd":"acceptSystemAlert","text":"Open"}
+{"cmd":"query","selector":"textContains=Continue"}
+{"cmd":"screenshot"}
+```
+
+Selector-addressed `tap`, `type`, and `eraseText` support these internal
+selector strings:
+
+- `text=<exact>` and `textContains=<substring>`
+- `label=<exact>` and `labelContains=<substring>`
+- `identifier=<exact>` and `identifierContains=<substring>`
+- `resourceId=<exact>` and `resourceIdContains=<substring>`
+- `id=<stable snapshot id>`
+- `value=<exact>` and `valueContains=<substring>`
+- `type=<XCUIElementType...>`
+
+`query` is the fast path used by Zig waits/assertions for single-field selectors
+that XCTest can evaluate natively. It returns:
+
+```json
+{"status":"ok","exists":true,"hittable":true}
+```
+
+`screenshot` returns a PNG payload encoded for the local shim transport:
+
+```json
+{"status":"ok","format":"png","base64":"..."}
+```
+
+Snapshot responses return bounded XCTest element data in a shape Zig can map
+into `UiNode`. The shim captures common interactive and readable element
+families and caps the response at 256 nodes so large application trees do not
+turn every snapshot into a full hierarchy crawl:
+
+```json
+{
+  "status": "ok",
+  "nodes": [
+    {
+      "id": "button-continue",
+      "type": "XCUIElementTypeButton",
+      "label": "Continue",
+      "value": "Continue",
+      "identifier": "continue_button",
+      "bounds": { "x": 10, "y": 20, "width": 100, "height": 44 },
+      "enabled": true,
+      "visible": true,
+      "selected": false
+    }
+  ]
+}
+```
+
+Errors use a stable envelope:
+
+```json
+{"status":"error","code":"selector.timeout","message":"selector did not match"}
+```

package/skills/zmr-mobile-testing/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: zmr-mobile-testing
+description: Use when testing mobile apps with Zig Mobile Runner, integrating app-local .zmr setup, driving Android or iOS simulator scenarios, using JSON-RPC or MCP agent sessions, exporting traces, or comparing mobile runner benchmarks.
+---
+
+# ZMR Mobile Testing
+
+Use ZMR as the typed control plane for mobile app testing. Keep model reasoning
+outside the runner; use ZMR for device discovery, observations, actions, waits,
+assertions, traces, and diagnostics.
+
+## Start From App-Local State
+
+1. Look for `.zmr/config.json` in the app checkout.
+2. If it is missing, scaffold it:
+
+   ```bash
+   npx zmr-wizard --app-id com.example.mobiletest --package-json
+   ```
+
+3. Run setup diagnostics before touching a device:
+
+   ```bash
+   zmr doctor --json --config .zmr/config.json
+   zmr validate --json .zmr/android-smoke.json
+   zmr validate --json .zmr/ios-smoke.json
+   ```
+
+Use `zmr doctor --strict --json` for CI-style gates.
+
+## Agent Session Pattern
+
+Prefer JSON-RPC over stdio for interactive agent work:
+
+```bash
+zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+Call methods in this order:
+
+1. `runner.capabilities`
+2. `session.create`
+3. `observe.semanticSnapshot` for planning, or `observe.snapshot` for raw adapter data
+4. one typed action, wait, or assertion
+5. `observe.semanticSnapshot`
+6. `trace.events` while the session is active
+7. `trace.export` with redaction enabled
+8. `session.close`
+
+Do not scrape terminal output when CLI JSON, snapshots, action results, or trace
+events contain the same information.
+
+For MCP-capable agents, start:
+
+```bash
+zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+Use the `semantic_snapshot`, `tap`, `type`, `wait_visible`, `trace_events`, and
+`trace_export` tools. Prefer `semantic_snapshot` because it normalizes Android
+and iOS hierarchy classes into roles, selectors, bounds, and recommended
+actions.
+
+## Scenario Pattern
+
+For repeatable tests, edit `.zmr/*.json` scenarios and run:
+
+```bash
+zmr validate --json .zmr/<scenario>.json
+zmr run .zmr/<scenario>.json --json --trace-dir traces/zmr-<scenario>
+zmr explain --json traces/zmr-<scenario>
+```
+
+Prefer stable selectors: resource id or accessibility identifier first,
+content description/accessibility label second, exact text third, textContains
+only when copy varies, coordinates last.
+
+Use `waitAny` for valid branches and `whenVisible` for optional screens. Keep
+credentials, private app terms, and private traces out of public docs and
+examples.
+
+## Trace Handling
+
+When a run fails, inspect `zmr explain --json`, `events.jsonl`, the final
+snapshot, and the trace viewer report from `zmr report`.
+
+Before sharing:
+
+```bash
+zmr export traces/zmr-<scenario> --out traces/zmr-<scenario>-redacted.zmrtrace --redact
+```
+
+Add `--omit-screenshots` if visual artifacts may contain sensitive data.
+
+## Release And Claim Guard
+
+Before reporting that ZMR is ready for a release, production use, or a market
+comparison, ask the runner to evaluate evidence instead of inferring from test
+passes:
+
+```bash
+zmr-release-readiness --json \
+  --evidence traces/release-candidate/<run>/evidence.jsonl \
+  --target dev-preview
+```
+
+For production or market claims, include app-local pilot and benchmark evidence
+with additional `--evidence` arguments. Read `satisfied` for proven requirements
+and `blocked`, `missing`, `insufficient`, `failed`, and `planned` for remaining
+work. Use `recommendedWording` as the release summary and respect
+`claimLimitations`; do not infer stronger claims from `passed` alone or upgrade
+a dev-preview result into a production-stable or competitive claim. When
+blocked, execute `nextSteps[].commands` in order and use `nextSteps[].covers`
+to understand which blocked requirements each step resolves.
+
+## Benchmarks
+
+Use ZMR repeated runs:
+
+```bash
+zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0
+```
+
+Use `zmr-benchmark-command` for any app-local baseline command and
+`zmr-compare-benchmarks` for reports. Only claim performance wins from
+equivalent app paths, same device state, repeated runs, and trace-backed
+failure diagnostics.

package/src/android.zig

@@ -0,0 +1,344 @@
+const std = @import("std");
+const command = @import("command.zig");
+const android_device_info = @import("android_device_info.zig");
+const android_shell = @import("android_shell.zig");
+const android_screen_recording = @import("android_screen_recording.zig");
+const ios_shim = @import("ios_shim.zig");
+const trace = @import("trace.zig");
+const types = @import("types.zig");
+const uiautomator = @import("uiautomator.zig");
+
+const default_max_output = 32 * 1024 * 1024;
+const default_adb_timeout_ms = 15_000;
+const install_adb_timeout_ms = 120_000;
+const shim_timeout_ms = 5_000;
+const open_link_attempts = 3;
+const open_link_retry_delay_ms = 500;
+
+pub const AndroidDevice = struct {
+    allocator: std.mem.Allocator,
+    adb_path: []const u8 = "adb",
+    serial: ?[]const u8 = null,
+    app_id: []const u8,
+    shim_path: ?[]const u8 = null,
+
+    pub fn init(
+        allocator: std.mem.Allocator,
+        adb_path: []const u8,
+        serial: ?[]const u8,
+        app_id: []const u8,
+    ) !AndroidDevice {
+        return try initWithShim(allocator, adb_path, serial, app_id, null);
+    }
+
+    pub fn initWithShim(
+        allocator: std.mem.Allocator,
+        adb_path: []const u8,
+        serial: ?[]const u8,
+        app_id: []const u8,
+        shim_path: ?[]const u8,
+    ) !AndroidDevice {
+        return .{
+            .allocator = allocator,
+            .adb_path = try allocator.dupe(u8, adb_path),
+            .serial = try types.dupeOptional(allocator, serial),
+            .app_id = try allocator.dupe(u8, app_id),
+            .shim_path = try types.dupeOptional(allocator, shim_path),
+        };
+    }
+
+    pub fn deinit(self: *AndroidDevice) void {
+        self.allocator.free(self.adb_path);
+        if (self.serial) |value| self.allocator.free(value);
+        self.allocator.free(self.app_id);
+        if (self.shim_path) |value| self.allocator.free(value);
+    }
+
+    pub fn listDevices(self: *AndroidDevice) ![]types.DeviceInfo {
+        return try android_device_info.listDevices(self.allocator, self.adb_path);
+    }
+
+    pub fn install(self: *AndroidDevice, apk_path: []const u8) !void {
+        const result = try self.runAdbWithTimeout(&.{ "install", "-r", apk_path }, default_max_output, install_adb_timeout_ms);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn launch(self: *AndroidDevice) !void {
+        const result = try self.runAdb(&.{ "shell", "monkey", "-p", self.app_id, "-c", "android.intent.category.LAUNCHER", "1" }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn stop(self: *AndroidDevice) !void {
+        const result = try self.runAdb(&.{ "shell", "am", "force-stop", self.app_id }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn clearState(self: *AndroidDevice) !void {
+        const result = try self.runAdb(&.{ "shell", "pm", "clear", self.app_id }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn openLink(self: *AndroidDevice, url: []const u8) !void {
+        var args = try android_shell.openLinkIntent(self.allocator, url, self.app_id);
+        defer args.deinit();
+        var attempt: usize = 0;
+        while (attempt < open_link_attempts) : (attempt += 1) {
+            const result = try self.runAdb(args.items(), default_max_output);
+            defer result.deinit(self.allocator);
+            try result.ensureSuccess();
+
+            if (self.isAppForeground() catch false) return;
+            if (attempt + 1 < open_link_attempts) {
+                std.Thread.sleep(open_link_retry_delay_ms * std.time.ns_per_ms);
+            }
+        }
+        return error.AppDidNotOpen;
+    }
+
+    pub fn tap(self: *AndroidDevice, x: i32, y: i32) !void {
+        if (self.shim_path != null) return try self.runShimAction(.{ .kind = .tap, .x = x, .y = y });
+        var args = try android_shell.tap(self.allocator, x, y);
+        defer args.deinit();
+        const result = try self.runAdb(args.items(), default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn typeText(self: *AndroidDevice, text: []const u8) !void {
+        if (self.shim_path != null) return try self.runShimAction(.{ .kind = .type_text, .text = text });
+        var args = try android_shell.typeText(self.allocator, text);
+        defer args.deinit();
+        const result = try self.runAdb(args.items(), default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn eraseText(self: *AndroidDevice, max_chars: u32) !void {
+        if (self.shim_path != null) return try self.runShimAction(.{ .kind = .erase_text, .max_chars = max_chars });
+        var args = try android_shell.eraseText(self.allocator, max_chars);
+        defer args.deinit();
+        const result = try self.runAdb(args.items(), default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn hideKeyboard(self: *AndroidDevice) !void {
+        if (self.shim_path != null) return try self.runShimAction(.{ .kind = .hide_keyboard });
+        var args = try android_shell.pressBack(self.allocator);
+        defer args.deinit();
+        const result = try self.runAdb(args.items(), default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn swipe(self: *AndroidDevice, x1: i32, y1: i32, x2: i32, y2: i32, duration_ms: u32) !void {
+        if (self.shim_path != null) return try self.runShimAction(.{ .kind = .swipe, .x1 = x1, .y1 = y1, .x2 = x2, .y2 = y2, .duration_ms = duration_ms });
+        var args = try android_shell.swipe(self.allocator, x1, y1, x2, y2, duration_ms);
+        defer args.deinit();
+        const result = try self.runAdb(args.items(), default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn pressBack(self: *AndroidDevice) !void {
+        if (self.shim_path != null) return try self.runShimAction(.{ .kind = .press_back });
+        var args = try android_shell.pressBack(self.allocator);
+        defer args.deinit();
+        const result = try self.runAdb(args.items(), default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
+    pub fn startScreenRecording(self: *AndroidDevice, remote_path: []const u8) !AndroidScreenRecording {
+        return try android_screen_recording.start(self.allocator, self.adb_path, self.serial, remote_path);
+    }
+
+    pub fn settle(self: *AndroidDevice, timeout_ms: u64) !void {
+        if (self.shim_path != null) {
+            return try self.runShimAction(.{
+                .kind = .settle,
+                .duration_ms = @as(u32, @intCast(@min(timeout_ms, std.math.maxInt(u32)))),
+            });
+        }
+        std.Thread.sleep(timeout_ms * std.time.ns_per_ms);
+    }
+
+    pub fn snapshot(self: *AndroidDevice, writer: ?*trace.TraceWriter) !types.ObservationSnapshot {
+        const id = if (writer) |tw| try tw.nextSnapshotId() else try std.fmt.allocPrint(self.allocator, "snapshot-{d}", .{std.time.milliTimestamp()});
+        errdefer self.allocator.free(id);
+
+        const xml = if (self.shim_path == null) try self.dumpHierarchy() else null;
+        defer if (xml) |value| self.allocator.free(value);
+        const nodes = if (self.shim_path) |_|
+            try self.snapshotNodesFromShim()
+        else
+            try uiautomator.parseHierarchy(self.allocator, xml.?);
+        errdefer {
+            for (nodes) |node| node.deinit(self.allocator);
+            self.allocator.free(nodes);
+        }
+
+        var screenshot_artifact: ?[]const u8 = null;
+        errdefer if (screenshot_artifact) |path| self.allocator.free(path);
+        var tree_artifact: ?[]const u8 = null;
+        errdefer if (tree_artifact) |path| self.allocator.free(path);
+
+        if (writer) |tw| {
+            if (tw.capture.capture_screenshots) {
+                const screenshot = self.captureScreenshot() catch null;
+                if (screenshot) |bytes| {
+                    defer self.allocator.free(bytes);
+                    const file_name = try std.fmt.allocPrint(self.allocator, "{s}.png", .{id});
+                    defer self.allocator.free(file_name);
+                    screenshot_artifact = try tw.writeArtifact(file_name, bytes);
+                }
+            }
+            if (tw.capture.capture_hierarchy and xml != null) {
+                const tree_name = try std.fmt.allocPrint(self.allocator, "{s}.xml", .{id});
+                defer self.allocator.free(tree_name);
+                tree_artifact = try tw.writeArtifact(tree_name, xml.?);
+            }
+        }
+
+        const active = try self.activeWindow();
+        errdefer active.deinit(self.allocator);
+
+        const screen = self.viewport() catch types.Viewport{};
+        const display_density_dpi = self.displayDensityDpi() catch null;
+        const capture_logs = if (writer) |tw| tw.capture.capture_logs else true;
+        const logs = if (capture_logs) self.logDelta() catch null else null;
+        errdefer if (logs) |value| self.allocator.free(value);
+
+        return .{
+            .id = id,
+            .timestamp_ms = std.time.milliTimestamp(),
+            .viewport = screen,
+            .display_density_dpi = display_density_dpi,
+            .active_package = active.package,
+            .active_activity = active.activity,
+            .screenshot_artifact = screenshot_artifact,
+            .tree_artifact = tree_artifact,
+            .focused_node_id = null,
+            .log_delta = logs,
+            .nodes = nodes,
+        };
+    }
+
+    fn dumpHierarchy(self: *AndroidDevice) ![]u8 {
+        const result = try self.runAdb(&.{ "exec-out", "uiautomator", "dump", "/dev/tty" }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+        return try self.allocator.dupe(u8, result.stdout);
+    }
+
+    fn captureScreenshot(self: *AndroidDevice) ![]u8 {
+        const result = try self.runAdb(&.{ "exec-out", "screencap", "-p" }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+        return try self.allocator.dupe(u8, result.stdout);
+    }
+
+    fn activeWindow(self: *AndroidDevice) !ActiveWindow {
+        const result = try self.runAdb(&.{ "shell", "dumpsys", "window" }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+        return try android_device_info.parseActiveWindow(self.allocator, result.stdout);
+    }
+
+    fn isAppForeground(self: *AndroidDevice) !bool {
+        const active = try self.activeWindow();
+        defer active.deinit(self.allocator);
+        const package = active.package orelse return false;
+        return std.mem.eql(u8, package, self.app_id);
+    }
+
+    fn viewport(self: *AndroidDevice) !types.Viewport {
+        const result = try self.runAdb(&.{ "shell", "wm", "size" }, 4096);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+        return android_device_info.parseViewport(result.stdout) catch types.Viewport{};
+    }
+
+    fn displayDensityDpi(self: *AndroidDevice) !?u32 {
+        const result = try self.runAdb(&.{ "shell", "wm", "density" }, 4096);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+        return android_device_info.parseDisplayDensityDpi(result.stdout);
+    }
+
+    fn logDelta(self: *AndroidDevice) !?[]const u8 {
+        const result = try self.runAdb(&.{ "logcat", "-d", "-t", "80" }, 1024 * 1024);
+        defer result.deinit(self.allocator);
+        if (result.term != .Exited or result.term.Exited != 0) return null;
+        return try self.allocator.dupe(u8, result.stdout);
+    }
+
+    fn snapshotNodesFromShim(self: *AndroidDevice) ![]types.UiNode {
+        const response = try self.runShim(.{ .kind = .snapshot });
+        defer self.allocator.free(response);
+        return try ios_shim.parseSnapshotNodes(self.allocator, response);
+    }
+
+    fn runShimAction(self: *AndroidDevice, shim_command: ios_shim.Command) !void {
+        const response = try self.runShim(shim_command);
+        defer self.allocator.free(response);
+        try ios_shim.parseOkResponse(response);
+    }
+
+    fn runShim(self: *AndroidDevice, shim_command: ios_shim.Command) ![]u8 {
+        const path = self.shim_path orelse return error.AndroidShimRequired;
+
+        var input = std.ArrayList(u8).empty;
+        defer input.deinit(self.allocator);
+        try ios_shim.writeCommandJson(input.writer(self.allocator), shim_command);
+
+        const result = try command.runWithInputTimeout(self.allocator, &.{path}, input.items, 4 * 1024 * 1024, shim_timeout_ms);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+        return try self.allocator.dupe(u8, result.stdout);
+    }
+
+    fn runAdb(self: *AndroidDevice, extra: []const []const u8, max_output_bytes: usize) !command.ExecResult {
+        return try self.runAdbWithTimeout(extra, max_output_bytes, default_adb_timeout_ms);
+    }
+
+    fn runAdbWithTimeout(self: *AndroidDevice, extra: []const []const u8, max_output_bytes: usize, timeout_ms: u64) !command.ExecResult {
+        var argv = std.ArrayList([]const u8).empty;
+        defer argv.deinit(self.allocator);
+        try self.appendAdbBase(&argv);
+        try argv.appendSlice(self.allocator, extra);
+        return try command.runWithTimeout(self.allocator, argv.items, max_output_bytes, timeout_ms);
+    }
+
+    fn appendAdbBase(self: *AndroidDevice, argv: *std.ArrayList([]const u8)) !void {
+        try argv.append(self.allocator, self.adb_path);
+        if (self.serial) |serial| {
+            try argv.append(self.allocator, "-s");
+            try argv.append(self.allocator, serial);
+        }
+    }
+};
+
+pub const AndroidScreenRecording = android_screen_recording.AndroidScreenRecording;
+
+pub fn listDevices(allocator: std.mem.Allocator, adb_path: []const u8) ![]types.DeviceInfo {
+    return try android_device_info.listDevices(allocator, adb_path);
+}
+
+pub const ActiveWindow = android_device_info.ActiveWindow;
+
+pub fn parseActiveWindow(allocator: std.mem.Allocator, dumpsys: []const u8) !ActiveWindow {
+    return try android_device_info.parseActiveWindow(allocator, dumpsys);
+}
+
+pub fn parseViewport(output: []const u8) !types.Viewport {
+    return try android_device_info.parseViewport(output);
+}
+
+pub fn parseDisplayDensityDpi(output: []const u8) ?u32 {
+    return android_device_info.parseDisplayDensityDpi(output);
+}

package/src/android_device_info.zig

@@ -0,0 +1,99 @@
+const std = @import("std");
+const command = @import("command.zig");
+const types = @import("types.zig");
+
+const default_adb_timeout_ms = 15_000;
+
+pub fn listDevices(allocator: std.mem.Allocator, adb_path: []const u8) ![]types.DeviceInfo {
+    const result = try command.runWithTimeout(allocator, &.{ adb_path, "devices" }, 1024 * 1024, default_adb_timeout_ms);
+    defer result.deinit(allocator);
+    try result.ensureSuccess();
+
+    var devices = std.ArrayList(types.DeviceInfo).empty;
+    errdefer {
+        for (devices.items) |device| device.deinit(allocator);
+        devices.deinit(allocator);
+    }
+
+    var lines = std.mem.splitScalar(u8, result.stdout, '\n');
+    _ = lines.next();
+    while (lines.next()) |raw_line| {
+        const line = std.mem.trim(u8, raw_line, " \t\r\n");
+        if (line.len == 0) continue;
+        var parts = std.mem.tokenizeAny(u8, line, " \t");
+        const serial = parts.next() orelse continue;
+        const state = parts.next() orelse continue;
+        try devices.append(allocator, .{
+            .serial = try allocator.dupe(u8, serial),
+            .state = try allocator.dupe(u8, state),
+        });
+    }
+
+    return try devices.toOwnedSlice(allocator);
+}
+
+pub const ActiveWindow = struct {
+    package: ?[]const u8 = null,
+    activity: ?[]const u8 = null,
+
+    pub fn deinit(self: ActiveWindow, allocator: std.mem.Allocator) void {
+        if (self.package) |value| allocator.free(value);
+        if (self.activity) |value| allocator.free(value);
+    }
+};
+
+pub fn parseActiveWindow(allocator: std.mem.Allocator, dumpsys: []const u8) !ActiveWindow {
+    const markers = [_][]const u8{ "mCurrentFocus=", "mFocusedApp=", "topResumedActivity=" };
+    for (markers) |marker| {
+        if (std.mem.indexOf(u8, dumpsys, marker)) |pos| {
+            const line_end = std.mem.indexOfScalarPos(u8, dumpsys, pos, '\n') orelse dumpsys.len;
+            const line = dumpsys[pos..line_end];
+            if (parsePackageActivity(allocator, line)) |active| return active else |_| continue;
+        }
+    }
+    return .{};
+}
+
+fn parsePackageActivity(allocator: std.mem.Allocator, line: []const u8) !ActiveWindow {
+    const slash = std.mem.indexOfScalar(u8, line, '/') orelse return error.NoActivity;
+    var pkg_start = slash;
+    while (pkg_start > 0) : (pkg_start -= 1) {
+        const ch = line[pkg_start - 1];
+        if (!(std.ascii.isAlphanumeric(ch) or ch == '_' or ch == '.')) break;
+    }
+    var activity_end = slash + 1;
+    while (activity_end < line.len) : (activity_end += 1) {
+        const ch = line[activity_end];
+        if (!(std.ascii.isAlphanumeric(ch) or ch == '_' or ch == '.' or ch == '$')) break;
+    }
+    if (pkg_start >= slash or activity_end <= slash + 1) return error.NoActivity;
+    return .{
+        .package = try allocator.dupe(u8, line[pkg_start..slash]),
+        .activity = try allocator.dupe(u8, line[slash + 1 .. activity_end]),
+    };
+}
+
+pub fn parseViewport(output: []const u8) !types.Viewport {
+    const marker = "Physical size:";
+    const start = std.mem.indexOf(u8, output, marker) orelse return error.NoViewport;
+    const after = std.mem.trim(u8, output[start + marker.len ..], " \t\r\n");
+    const x = std.mem.indexOfScalar(u8, after, 'x') orelse return error.NoViewport;
+    var end: usize = x + 1;
+    while (end < after.len and std.ascii.isDigit(after[end])) : (end += 1) {}
+    return .{
+        .width = try std.fmt.parseInt(u32, std.mem.trim(u8, after[0..x], " \t"), 10),
+        .height = try std.fmt.parseInt(u32, after[x + 1 .. end], 10),
+    };
+}
+
+pub fn parseDisplayDensityDpi(output: []const u8) ?u32 {
+    var lines = std.mem.splitScalar(u8, output, '\n');
+    while (lines.next()) |raw_line| {
+        const line = std.mem.trim(u8, raw_line, " \t\r\n");
+        const prefix = "Physical density:";
+        if (!std.mem.startsWith(u8, line, prefix)) continue;
+        const value = std.mem.trim(u8, line[prefix.len..], " \t\r\n");
+        return std.fmt.parseInt(u32, value, 10) catch null;
+    }
+    return null;
+}