zig-mobile-runner 0.1.0

package/docs/ai-agents.md

@@ -0,0 +1,156 @@
+# AI Agent Guide
+
+ZMR is built for external agents. The runner provides device state, typed
+actions, waits, assertions, and trace export; the agent decides the next step.
+
+## Agent Setup Loop
+
+Start inside the app checkout:
+
+```bash
+zmr doctor --json --config .zmr/config.json
+zmr validate --json .zmr/android-smoke.json
+zmr validate --json .zmr/ios-smoke.json
+zmr schemas --json
+```
+
+Use `zmr doctor --strict --json` in CI or setup flows that should fail on any
+warning. Prefer JSON output for automation because it includes stable error
+codes, field paths, and remediation hints.
+
+## Live JSON-RPC Session
+
+Agents should prefer `zmr serve` for interactive work:
+
+```bash
+zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+Recommended flow:
+
+1. Call `runner.capabilities` and check protocol/platform support.
+2. Call `session.create`.
+3. Call `observe.semanticSnapshot` when choosing the next action, or
+   `observe.snapshot` when raw adapter details are needed.
+4. Choose one typed action or assertion.
+5. Let ZMR settle, then observe again.
+6. Poll `trace.events` during long runs.
+7. Call `trace.export` with `redact: true` before sharing artifacts.
+8. Call `session.close`.
+
+Do not parse screenshots or terminal text when the same fact is available from
+snapshot nodes, action results, CLI JSON, or trace events.
+
+If `zmr run --json` returns `status: "partial"`, inspect `partialFailure`.
+For iOS visual captures, `artifactStatus: "captured"` with
+`semanticStatus: "failed"` means screenshot proof exists but accessibility or
+XCTest hierarchy extraction failed. Use `zmr explain --json <trace-dir>` for
+the same diagnostic shape after the run.
+
+## MCP Session
+
+Agents that support the Model Context Protocol can use ZMR directly as a local
+stdio MCP server:
+
+```bash
+zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+The MCP server exposes mobile-specific tools:
+
+- `snapshot`: raw ZMR observation JSON
+- `semantic_snapshot`: normalized roles, names, selectors, bounds, and
+  recommended actions
+- `tap`, `type`, `press_back`, and `open_link`
+- `wait_visible`
+- `trace_events` and `trace_export`
+
+Prefer `semantic_snapshot` for action planning. It avoids forcing an agent to
+infer intent from platform-specific Android/UI Automator or XCTest class names.
+
+## Scenario File Workflow
+
+For repeatable tests, generate or edit `.zmr/*.json` scenarios:
+
+```bash
+zmr validate --json .zmr/login-smoke.json
+zmr run .zmr/login-smoke.json --json --trace-dir traces/zmr-login-smoke
+zmr explain --json traces/zmr-login-smoke
+zmr export traces/zmr-login-smoke --out traces/zmr-login-smoke-redacted.zmrtrace --redact
+```
+
+Use stable selectors in this order when available:
+
+- app accessibility identifiers or resource ids
+- content descriptions or accessibility labels
+- exact visible text for stable product copy
+- `textContains` only when the visible text legitimately varies
+- coordinate actions only as a last resort
+
+Use `waitAny` for screens with legitimate branches, and `whenVisible` for
+optional platform or dev-client screens. Keep credentials and app-private data
+in the app repository or environment, not in public scenarios.
+
+## Failure Triage
+
+When a run fails, inspect:
+
+- `zmr run --json` terminal summary
+- `zmr explain --json <trace-dir>`
+- `trace.json`
+- `events.jsonl`
+- the last snapshot JSON
+- the trace viewer report from `zmr report`
+
+Selector failures include active app context, visible text, disabled/hidden or
+offscreen exact candidates, and nearest text matches when available. Treat
+those diagnostics as the source of truth before changing a selector.
+
+## Benchmarking
+
+Use ZMR repeated runs first:
+
+```bash
+zmr-benchmark --zmr .zmr/android-smoke.json --platform android --device emulator-5554 --app-id com.example.mobiletest --app-build <build-id-or-artifact> --runs 20 --trace-root traces/zmr-android-reliability --results traces/bench-comparison/results.jsonl --replace --min-pass-rate 100 --max-failures 0
+```
+
+For a fair comparison with an app-local baseline command, collect normalized
+rows and compare them:
+
+```bash
+zmr-benchmark-command --tool baseline --platform android --device emulator-5554 --app-id com.example.mobiletest --scenario .zmr/android-smoke.json --app-build <build-id-or-artifact> --runs 20 --trace-root traces/baseline --results traces/bench-comparison/results.jsonl -- <baseline command>
+zmr-compare-benchmarks --results traces/bench-comparison/results.jsonl --candidate zmr --baseline baseline --min-candidate-pass-rate 100 --max-candidate-failures 0 --min-mean-speedup 1.25 --min-p95-speedup 1.25 --out traces/bench-comparison/comparison.md --evidence-out traces/bench-comparison/evidence.jsonl
+```
+
+Only publish claims when the candidate and baseline exercise equivalent app
+paths under the same device state. Market-claim evidence must show the same
+benchmark context: `platform`, `device`, `appId`, `scenario`, and `appBuild`.
+It must also include at least 20 candidate rows and at least 20 baseline rows.
+
+## Release Claims
+
+Before saying a release, production rollout, or market comparison is ready,
+evaluate the collected evidence:
+
+```bash
+zmr-release-readiness --json \
+  --evidence traces/release-candidate/<run>/evidence.jsonl \
+  --target dev-preview
+```
+
+Use `satisfied` for proven requirements and `blocked`, `missing`,
+`insufficient`, `failed`, and `planned` for remaining work. Use
+`recommendedWording` for the human-facing status and keep
+`claimLimitations` intact; never upgrade a dev-preview result into a
+production-stable or competitive claim. When blocked, run
+`nextSteps[].commands` in order and use `nextSteps[].covers` to map each
+command back to the blocked requirements it resolves.
+
+## Safety Rules
+
+- Run `tests/public-safety-test.sh` before publishing docs, examples, or traces.
+- Do not commit app-private traces, screenshots, credentials, tokens, bundle
+  identifiers, or private app names.
+- Prefer `zmr export --redact`; add `--omit-screenshots` for public bundles
+  when visual artifacts may contain sensitive data.
+- Keep app-local state under `.zmr/` and generated run output under `traces/`.

package/docs/app-integration.md

@@ -0,0 +1,316 @@
+# App Integration
+
+ZMR is intentionally a separate runner. A mobile app repo does not need to vendor ZMR, but it should expose a small, stable test surface so agents can drive the app deterministically.
+
+Most app teams should install ZMR as a dev dependency:
+
+```bash
+npm install --save-dev zig-mobile-runner
+npx zmr-wizard --app-id com.example.mobiletest --package-json
+```
+
+That keeps scenarios and app scripts in the app repo while the runner remains versioned through npm.
+For Expo development builds, add `--expo-dev-client-scheme <scheme>` to scaffold
+Android and iOS open-link smoke scenarios that load Metro before selector
+assertions run.
+
+## What The App Provides
+
+For Android:
+
+- A debug/test APK.
+- A stable application id, for example `com.example.mobiletest`.
+- Optional deep links for direct navigation into test states.
+- Accessibility labels, text, or resource ids for important controls.
+- A test server or local dev server when the app requires one.
+- Optional Android instrumentation shim command for faster hierarchy and
+  selector-grade actions.
+
+Create the app-local Android shim command from the ZMR package or checkout:
+
+```bash
+npx zmr-install-android-shim \
+  --app-root . \
+  --test-package com.example.mobiletest.test \
+  --runner androidx.test.runner.AndroidJUnitRunner \
+  --android-module android/app \
+  --gradle-file android/app/build.gradle
+```
+
+With `--android-module`, the installer copies the shim into the app module's
+standard `src/androidTest/java/dev/zmr/shim/` tree. With `--gradle-file`, it
+appends guarded Gradle blocks once for `testInstrumentationRunner` and AndroidX
+Test/UI Automator dependencies. If the Gradle file already declares a custom
+`testInstrumentationRunner` and `--runner` is omitted, the generated shim command
+uses the existing runner. Omit those flags when you prefer to wire source and
+dependencies yourself from the generated `.zmr/ZMRShimInstrumentedTest.java`.
+The generated
+`.zmr/android-shim` executable is the value to pass to `--android-shim` or
+`tools.androidShimPath`.
+
+For iOS:
+
+- A simulator `.app` build.
+- A stable bundle id, for example `com.example.mobiletest`.
+- Optional deep links for direct navigation into test states.
+- Accessibility labels for important controls.
+- Optional simulator XCTest/XCUIAutomation shim command for hierarchy and
+  selector-grade actions.
+
+Create the app-local shim command from the ZMR package or checkout:
+
+```bash
+npx zmr-install-ios-shim \
+  --app-root . \
+  --scheme SampleUITests \
+  --test-target SampleUITests \
+  --workspace ios/Sample.xcworkspace \
+  --app-target SampleApp \
+  --derived-data-path ios/build/ZMRDerivedData \
+  --bundle-id com.example.mobiletest \
+  --patch-xcodeproj
+```
+
+Run `.zmr/ensure-ios-shim-target.sh` to create/update the UI test target, add
+the generated `.zmr/ZMRShimUITestCase.swift` and
+`.zmr/shims/ios/ZMRShim.swift` files, configure
+`.zmr/ZMRShimUITests-Info.plist`, and write a shared scheme. The helper uses the
+Ruby `xcodeproj` gem. With `--workspace`, it resolves the referenced
+`.xcodeproj` automatically when there is one project, or when exactly one
+project contains `--app-target`, or when `--bundle-id` disambiguates matching
+app targets. Pass `--project ios/Sample.xcodeproj` explicitly for
+still-ambiguous multi-project workspaces or project-only apps.
+
+The generated `.zmr/ios-shim` executable is written into
+`tools.iosShimPath` in `.zmr/config.json`, and can still be passed explicitly
+with `--ios-shim`. It caches `build-for-testing` output and uses
+`test-without-building` for selector commands through `.zmr/ios-shim-state/`.
+Set `ZMR_IOS_SHIM_FORCE_REBUILD=1` after app-side target changes, or
+`ZMR_IOS_SHIM_ONESHOT=1` when you need to debug the slower cold-start path.
+
+## Recommended App Repo Layout
+
+The exact layout is app-specific, but this shape works well:
+
+```text
+mobile-app/
+  android/app/build/outputs/apk/debug/app-debug.apk
+  build/Debug-iphonesimulator/Sample.app
+  .zmr/
+    config.json
+    android-auth-probe.json
+    android-login-smoke.json
+    ios-smoke.json
+```
+
+Keep app-owned scenarios and ZMR defaults in `.zmr/` when they are app-specific. Keep generic examples in the ZMR repo. ZMR auto-discovers `.zmr/config.json` from the app repo; explicit CLI flags still override config defaults.
+
+## Android App Pilot Command
+
+```bash
+/path/to/zig-mobile-runner/scripts/run-android-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-id com.example.mobiletest \
+  --device emulator-5554
+```
+
+Use a saved emulator snapshot for repeatability:
+
+```bash
+/path/to/zig-mobile-runner/scripts/run-android-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-id com.example.mobiletest \
+  --device emulator-5554 \
+  --avd Small_Phone \
+  --reset-emulator \
+  --restore-snapshot zmr-clean \
+  --screen-record
+```
+
+`--screen-record` writes `screenrecord.mp4` under the pilot trace root. For
+direct traced runs, use `zmr run --android-avd Small_Phone
+--create-avd-if-missing --avd-system-image
+'system-images;android-35;google_apis;arm64-v8a' --avd-device pixel_6
+--restore-snapshot zmr-clean --wait-emulator --screen-record`, or set the
+equivalent `android.avdName`, `android.createAvdIfMissing`,
+`android.avdSystemImage`, `android.avdDeviceProfile`,
+`android.restoreSnapshot`, `android.waitReady`, and
+`artifacts.screenRecording` values in `.zmr/config.json`. Treat recordings like
+screenshots: keep them local or share only when the app state is safe.
+
+The Android wrapper expects the default APK path under the app root. Override it when needed:
+
+```bash
+/path/to/zig-mobile-runner/scripts/run-android-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --apk /path/to/app-debug.apk \
+  --device emulator-5554
+```
+
+## Public Android Demo Command
+
+For a generic public Android app:
+
+```bash
+npx zmr-demo-android --out /tmp/zmr-android-demo --device emulator-5554 --avd <avd-name>
+```
+
+This writes a signed debug APK plus `.zmr/android-smoke.json` without Gradle or
+network access, then installs and runs it on the requested Android target. For
+manual inspection or customization:
+
+```bash
+npx zmr-create-android-demo-app --out /tmp/zmr-android-demo
+adb install -r /tmp/zmr-android-demo/build/app-debug.apk
+/path/to/zig-mobile-runner/zig-out/bin/zmr run /tmp/zmr-android-demo/.zmr/android-smoke.json \
+  --device emulator-5554 \
+  --app-id com.example.mobiletest \
+  --trace-dir /tmp/zmr-android-demo/traces/android-demo
+```
+
+Use this path to prove local Android install, launch, selector action, typing,
+snapshot, and trace capture before wiring ZMR into a private app.
+
+## iOS Demo Command
+
+For a generic public demo app with the shim already installed:
+
+```bash
+npx zmr-demo-ios --out /tmp/zmr-ios-demo --device booted
+```
+
+That command creates the demo app, boots an available simulator when needed,
+builds it, runs the iOS pilot, and writes redacted trace bundles. To inspect or
+customize the generated app before running the pilot manually:
+
+```bash
+npx zmr-create-ios-demo-app --out /tmp/zmr-ios-demo
+cd /tmp/zmr-ios-demo
+xcodebuild -project ios/ZMRDemo.xcodeproj -scheme ZMRDemo -destination 'generic/platform=iOS Simulator' -derivedDataPath DerivedData build
+```
+
+Then boot a simulator and run:
+
+```bash
+/path/to/zig-mobile-runner/scripts/run-ios-pilot.sh \
+  --app-root /tmp/zmr-ios-demo \
+  --app-path /tmp/zmr-ios-demo/DerivedData/Build/Products/Debug-iphonesimulator/ZMRDemo.app \
+  --app-id com.example.mobiletest \
+  --device booted \
+  --ios-shim /tmp/zmr-ios-demo/.zmr/ios-shim
+```
+
+Build the app for an iOS simulator, boot a simulator, then run:
+
+```bash
+/path/to/zig-mobile-runner/scripts/run-ios-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app \
+  --app-id com.example.mobiletest \
+  --device booted \
+  --ios-shim /path/to/mobile-app/.zmr/ios-shim
+```
+
+Without `--ios-shim`, the iOS path is a smoke demo: install, launch/open-link,
+screenshot, logs, trace, report, and redacted export. With `--ios-shim`, ZMR
+also runs `examples/ios-shim-smoke.json`, producing a second report and
+redacted bundle for selector-grade native waits, tap, type, and bounded
+snapshot actions. If a selector wait times out, ZMR records a final XCTest
+snapshot when possible so reports and agents can see the active app context,
+visible labels, hidden/disabled/offscreen candidates, and nearest text matches.
+When the app is already running, ZMR uses the shim `appState` response as an
+idempotent launch confirmation if `simctl launch` itself returns an error.
+
+On iOS simulators, `clearState` means best-effort app uninstall by bundle id.
+For physical iOS devices, lifecycle commands go through `devicectl` and
+selector commands go through the same app-local XCTest shim, subject to signing,
+provisioning, Developer Mode, and local Xcode availability. Screenshot
+artifacts use the XCTest shim; log artifact capture is simulator-first in this
+release.
+Use a simulator-built `iphonesimulator` `.app` for simulator runs. A signed
+device `.ipa` must be run with `--ios-device-type physical`; the pilot wrapper
+rejects device IPAs on simulator runs before installing anything.
+Use `--ios-device-type physical` with a concrete device identifier from
+`zmr devices` for physical pilot runs:
+
+```bash
+/path/to/zig-mobile-runner/scripts/run-ios-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-path /path/to/mobile-app/build/Release-iphoneos/Sample.ipa \
+  --ios-device-type physical \
+  --device <physical-device-id> \
+  --ios-shim /path/to/mobile-app/.zmr/ios-shim \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0
+```
+
+If the app is already missing, ZMR treats the simulator as clean and continues.
+Install the simulator `.app` again before launch/open-link steps that need it.
+
+## Direct CLI Use
+
+Android:
+
+```bash
+zmr run .zmr/android-auth-probe.json \
+  --device emulator-5554 \
+  --app-id com.example.mobiletest \
+  --android-shim ./.zmr/android-shim \
+  --trace-dir traces/android-auth
+```
+
+Or use app-local defaults:
+
+```bash
+zmr run --config .zmr/config.json
+```
+
+iOS:
+
+```bash
+xcrun simctl install booted /path/to/Sample.app
+zmr run .zmr/ios-shim-smoke.json \
+  --platform ios \
+  --device booted \
+  --app-id com.example.mobiletest \
+  --ios-shim ./.zmr/ios-shim \
+  --trace-dir traces/ios-smoke
+```
+
+## Agent JSON-RPC Use
+
+Start a local server next to the device. App repos scaffolded by
+`zmr-wizard --package-json` can use the generated scripts:
+
+```bash
+npm run zmr:serve
+npm run zmr:mcp
+```
+
+External agents can call:
+
+- `runner.capabilities`
+- `session.create`
+- `app.launch`
+- `app.openLink`
+- `observe.snapshot`
+- `observe.semanticSnapshot`
+- `ui.tap`
+- `wait.until`
+- `assert.visible`
+- `trace.export`
+
+Use `observe.semanticSnapshot` before choosing actions, and use
+`observe.snapshot` when raw adapter details are needed. Every action should
+settle and observe again. Scenario runs call the adapter-level settle hook after
+mutating actions; native shims can wait for platform idle while shell-only paths
+keep a bounded sleep fallback. Start `serve` with `--trace-dir` so
+`trace.export` can produce a redacted `.zmrtrace` bundle for the whole agent
+session.
+
+## Public Artifact Rules
+
+- Share `*-redacted.zmrtrace` bundles.
+- Do not publish raw Metro logs, simulator logs, or unredacted screenshot bundles from private apps.
+- Run `bash tests/public-safety-test.sh` before publishing this repo.