1# Llimphi · Android
2
3Port nativo de Llimphi a Android. Una `NativeActivity` en C que
4delega al `android_main` que `android-activity` exporta desde la
5`.so` Rust, idéntico patrón que un binario `main()` en desktop.
6
7## Estado
8
9| crate | estado |
10|---|---|
11| `clear-screen-android` | ✓ APK firmado v2, instalable en Android 7+ |
12| resto de apps Llimphi | pendientes — el patrón es reusar `android_main` |
13
14## Tesis
15
16El motor Llimphi (HAL + raster + layout + text + ui) **no se toca**.
17Lo único nuevo por target Android es:
18
191. Entry-point `#[no_mangle] android_main(app: AndroidApp)` en vez de
20   `fn main()`.
212. Construir el `EventLoop` con `with_android_app(app)` para que
22   `winit` reciba `Resumed` / `Suspended` / `InputAvailable` desde el
23   Looper de Android.
243. Recrear la `Surface` en cada `Resumed`: Android invalida la
25   NativeWindow al pasar a background. El `App::state: Option<State>`
26   ya está estructurado para eso.
27
28Las apps existentes que viven sobre Llimphi compilan sin cambios — lo
29que se reescribe es el **lifecycle wrapper**, no la lógica de render
30ni los widgets.
31
32## Cómo construir
33
34Una sola pasada — el script wrapper:
35
36```sh
37./scripts/build-android.sh clear-screen-android
38```
39
40Resultado: `target/x/release/android/clear-screen-android.apk`
41firmado con APK Signature Scheme v2, listo para
42`adb install -r <apk>`.
43
44## Setup inicial (una vez por máquina)
45
46```sh
47# Targets Rust
48rustup target add aarch64-linux-android x86_64-linux-android
49
50# Wrapper de build de Rust mobile (binario `x`)
51cargo install xbuild
52
53# NDK r27c (~640 MB descomprimido, ~1.5 GB)
54curl -L -o /tmp/ndk.zip \
55  https://dl.google.com/android/repository/android-ndk-r27c-linux.zip
56unzip /tmp/ndk.zip -d $HOME/
57export ANDROID_NDK_HOME=$HOME/android-ndk-r27c
58
59# SDK (sólo build-tools + platform-tools, no se necesita la plataforma
60# completa porque el APK se genera con aapt2 + apksigner del SDK).
61# En Artix viene del paquete `android-sdk-build-tools`.
62```
63
64El script `build-android.sh` genera automáticamente un PEM RSA2048
65self-signed en `~/.local/share/llimphi-android/debug.pem` la primera
66vez que corre. Para firma de release usar un PEM propio y exportarlo
67en `LLIMPHI_PEM`.
68
69## Estructura del APK generado
70
71```
72clear-screen-android.apk
73├── AndroidManifest.xml          ← xbuild genera; NativeActivity
74└── lib/arm64-v8a/
75    └── libclear_screen_android.so  ← 7.5 MB sin strip, ~2 MB stripped
76```
77
78Sin assets, sin recursos, sin Java/Kotlin. Todo el "código" de la app
79es la `.so` Rust. El bootstrap Java de NativeActivity lo provee el
80framework Android.
81
82## Apps por portar (orden de menor a mayor fricción)
83
84Las apps que **menos** se modifican al portar son las que ya tienen
85poca interacción con teclado/mouse y mucho rendering:
86
871. **mirada-image-viewer-llimphi** — visor de imágenes, gestos = ok
882. **nahual-text-viewer-llimphi** — sólo scroll + zoom
893. **nahual-image-viewer-llimphi** — idem
904. **pluma-md-reader** — visor markdown, mismo patrón que la web
915. **chasqui-explorer-llimphi** — listas y tarjetas, taps obvios
926. **shuma-shell-llimphi** — teclado virtual, ya casi no usa shortcuts
937. **mirada-app-llimphi** — el compositor; touch desktop = problema UX
94
95Las apps con paleta de comandos (nada, pluma-app full) son las
96**últimas** porque su UX core (Ctrl+Shift+P, multi-pane splitter,
97file picker) necesita ser repensada para touch.
98
99## Próximos hitos
100
101- **Tier 1.5**: hello-world con vello rasterizando un texto + figura
102  (smoke test del stack raster completo en Android).
103- **Tier 2**: portar `mirada-image-viewer-llimphi` — primer APK
104  funcional con UI real.
105- **Tier 3**: input handling proper (touch events, soft keyboard,
106  back button), theming responsivo (dpi/density).
107- **Tier 4**: distribución (Play Store internal track, F-Droid build
108  reproducible).