# Hook Echo-WX for Android

The Android app is the **same Rust codebase** as the desktop build, compiled to a `cdylib`
(`libhookecho.so`) and loaded by a `GameActivity` — `android_main` in
[`crates/hookecho/src/lib.rs`](../crates/hookecho/src/lib.rs) is the entry point, and Rust draws
every pixel. The Kotlin is deliberately thin: the activity itself (deep links + predictive back),
the background alert service, and the home-screen widget.

GameActivity rather than NativeActivity for one reason — GameTextInput is the real system IME.
Its editor state is bridged into egui events by `platform::pump_ime`; nothing upstream does that
for you. It also requires an AppCompat theme (`res/values/themes.xml`) or the activity throws on
creation.

- **Target:** `arm64-v8a`, minSdk 29 (Android 10), Vulkan.
- **What differs from desktop:** storage routes to the app-private data dir
  ([`paths.rs`](../crates/hookecho/src/paths.rs)); native file dialogs are replaced by a fixed
  `exports/` folder ([`dialog.rs`](../crates/hookecho/src/dialog.rs)); the tray, gpsd GPS, and MP4
  export (ffmpeg) are hidden; the UI is a Material 3 layout (map-first, one persistent bottom sheet with snap points, a docked
  toolbar, full-screen surfaces instead of floating windows) rather than the desktop chrome —
  see [`app/mobile/`](../crates/hookecho/src/app/mobile/) and the tokens in
  [`ui/m3.rs`](../crates/hookecho/src/ui/m3.rs); field grids decimate to
  the device's real texture cap. Everything else — the radar/MRMS/HRRR pipelines and every data
  feature — is shared, unchanged.

## Build locally

Prerequisites:

- Android SDK + NDK (r26+); set `ANDROID_HOME` and `ANDROID_NDK_HOME`
- JDK 17+
- `rustup target add aarch64-linux-android`
- `cargo install cargo-ndk`

Then, from the repo root:

```sh
android/build.sh            # release .so in a debug-signed APK (directly sideloadable)
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
```

`INSTALL=1 android/build.sh` installs it for you. The Rust library is always
optimised; `build.sh debug` builds an opt-level-0 `.so` with symbols for native crash
hunts, and `build.sh signed` produces a release-signed APK. `FEATURES=profiling
android/build.sh` enables the puffin server (see `crates/hookecho/src/profiling.rs`).

## First run

The setup wizard opens (home radar, theme, alerting). Background alerting is **not** a goal on
Android — the OS starves backgrounded processes; phone alerts come from the existing ntfy.sh push
(set an ntfy topic in Settings and install the ntfy app).

## Status

Phases 0–1 of the port (lib split, Android entry, platform gating, storage, touch input, CI) are in
place. On-device polish (soft-keyboard IME, drawer toolbox, JNI GPS, Storage-Access-Framework
import, Play Store) is tracked as deferred work in the port plan. The APK build itself runs in the
release workflow; a physical device is needed to exercise the GUI.