A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.
docs: update skill.md with complete architecture details and build commands
ExTvf9171affeef7
diff --git a/skill.md b/skill.mdindex 9de010d..0568026 100644--- a/skill.md+++ b/skill.md@@ -1,19 +1,20 @@# Podroid AI Context-> **Last updated:** 2026-04-15-> **Purpose:** Complete project context for AI-assisted development without re-explaining structure every prompt.+> **Last updated:** 2026-04-22+> **Purpose:** Complete project context for AI-assisted development. Read this before touching any file.---## Project Overview-**Podroid** is an Android app that runs Linux containers (Podman) on arm64 Android devices without root required. It spins up a lightweight Alpine Linux VM using QEMU and provides a built-in serial terminal.+**Podroid** is an Android app that runs rootless Podman containers on arm64 Android devices with no root required. It spins up a headless Alpine Linux 3.23 VM using QEMU TCG and exposes a serial console terminal inside the app.-- **Package:** `com.excp.podroid`-- **Min SDK:** 28 (Android 9.0)+- **Package:** `com.excp.podroid` (debug: `com.excp.podroid.debug`)+- **Min SDK:** 28 (Android 9.0)- **Target SDK:** 36-- **Architecture:** AArch64 only-- **License:** GNU GPL v2.0+- **Architecture:** AArch64 only (no x86/x86_64)+- **Root project name in Gradle:** `VirtuDroid`+- **GitHub:** https://github.com/ExTV/Podroid---@@ -21,15 +22,15 @@| Layer | Technology ||-------|------------|-| UI | Jetpack Compose (Material 3) |-| DI | Hilt |-| Async | Kotlin Coroutines + Flow |+| UI | Jetpack Compose + Material 3 |+| DI | Hilt (constructor injection, no @Provides) |+| Async | Kotlin Coroutines + StateFlow || Persistence | DataStore Preferences |-| Terminal | Termux TerminalView (VT100/xterm emulation) |-| VM | QEMU TCG (no KVM) |+| Terminal | Termux TerminalView v0.118.1 (JitPack AAR) |+| VM | QEMU 11.0.0-rc2 TCG (no KVM) || Container Runtime | Podman + crun + netavark + slirp4netns |-| Init System | Custom two-phase initramfs (`init-podroid`) |-| VM Linux | Alpine Linux 3.23 |+| VM Init | Custom two-phase shell script (`init-podroid`) |+| VM Linux | Alpine Linux 3.23 aarch64 |---@@ -38,20 +39,30 @@### High-Level Flow```Android App-├── Foreground Service (PodroidService) ← keeps VM alive-├── PodroidQemu engine-│ ├── QEMU process (libqemu-system-aarch64.so)-│ ├── Serial socket → boot monitor-│ └── QMP socket (port forwarding, VM control)-└── Jetpack Compose UI- └── Screens: Home, Terminal, Settings, Setup+├── PodroidApplication — extracts assets (vmlinuz, initrd, qemu/) on first run+├── PodroidService (foreground) — hosts QEMU, holds WakeLock+├── PodroidQemu (singleton)+│ ├── QEMU process (libqemu-system-aarch64.so — ELF binary renamed .so for APK)+│ ├── serial.sock — boot monitor reads until "Ready!", then bridge connects+│ ├── ctrl.sock — virtio-console for RESIZE signals from bridge+│ └── qmp.sock — QEMU Machine Protocol for runtime control+└── Compose UI+ └── Screens: Setup → Home → Terminal / Settings```-### VM Boot Sequence-1. QEMU loads `vmlinuz-virt` + `initrd.img`-2. Phase 1 (`init-podroid`): Mounts persistent ext4 disk as overlayfs upper layer-3. Phase 2 (`--main`): Configures networking, Podman, Dropbear SSH, starts getty on ttyAMA0-4. Terminal connects to serial console+### VM Boot Sequence (critical — read carefully)+1. QEMU starts, creates `serial.sock` (unix socket, server, single-client)+2. **Boot monitor** (`PodroidQemu.monitorBootSerial`) connects first to `serial.sock`, streams output to `console.log` and parses `boot_stage` strings for the Android UI+3. `init-podroid` Phase 1 (running in initramfs): mounts virtio-blk as ext4, creates overlayfs (`lowerdir=/`, `upperdir=/mnt/persist/upper`), `chroot /mnt/overlay /init --main`+4. `init-podroid` Phase 2 (`--main`): kernel modules → networking → containers → SSH → getty on ttyAMA0+5. Phase 2 emits `boot_stage "Ready!"` then **sleeps 2 seconds** (critical — lets boot monitor finish reading "Ready!" before bridge steals the single-client socket)+6. `detectBootStage("Ready!")` fires → `_state = Running` → `autoStartBridge()`+7. **`releaseSerial()`** closes boot monitor socket (`shutdownInput + shutdownOutput + close`)+8. **500ms delay** then `TerminalSession` launched with `libpodroid-bridge.so` as subprocess+9. Bridge binary connects to `serial.sock`, relays PTY ↔ serial bidirectionally++### Single-Client Socket Constraint+`serial.sock` is QEMU `server,nowait` — only ONE client at a time. Boot monitor connects first. `releaseSerial()` frees it. Bridge has a 50×200ms retry loop. The `sleep 2` in init-podroid and the 500ms `postDelayed` in `autoStartBridge()` are both critical timing guards.---@@ -60,100 +71,95 @@ Android App### Root Level```/-├── app/ # Android application-├── init-podroid # Custom VM init script (shell)-├── podroid-bridge.c # Native PTY↔serial.sock relay binary-├── build.gradle.kts # Root build config-├── settings.gradle.kts # Gradle settings-├── gradle.properties # Gradle + QEMU version (11.0.0-rc2)-├── Dockerfile # Multi-stage initramfs builder-├── Dockerfile.qemu # QEMU Docker build-├── docker-build-initramfs.sh # Initramfs build script-├── build-termux-android.sh # Termux native library build-├── build-qemu-android.sh # QEMU Android build-└── gradle/, gradlew, gradlew.bat # Gradle wrapper+├── app/ # Android application module+├── init-podroid # VM init script (baked into initrd.img as /init)+├── podroid-bridge.c # Native PTY↔serial relay (compiled to libpodroid-bridge.so)+├── Dockerfile # Unified multi-stage: downloader → rootfs-builder → packer → qemu-builder → final+├── build-all.sh # Unified build+deploy script+├── gradle.properties # podroidQemuVersion=11.0.0-rc2+├── build.gradle.kts, settings.gradle.kts+└── gradle/, gradlew```### app/src/main/java/com/excp/podroid/```-├── MainActivity.kt # Single activity entry point-├── PodroidApplication.kt # Hilt Application - asset extraction on first run+├── MainActivity.kt # Single Activity, WindowSizeClass, Hilt entry point+├── PodroidApplication.kt # Hilt @HiltAndroidApp, asset extraction on first run│├── engine/-│ ├── PodroidQemu.kt # QEMU lifecycle, serial.sock boot monitor, ctrl.sock chardev-│ │ └── KEY: releaseSerial() closes boot monitor so podroid-bridge can connect-│ ├── QmpClient.kt # QEMU QMP socket client for runtime port forwards-│ └── VmState.kt # Sealed class: Idle, Starting, Running, Paused, Saving, Resuming, Stopped, Error+│ ├── PodroidQemu.kt # QEMU lifecycle, boot monitor, bridge session, resize+│ ├── QmpClient.kt # QMP socket client (runtime port forwarding)+│ └── VmState.kt # Sealed: Idle|Starting|Running|Paused|Saving|Resuming|Stopped|Error│├── service/-│ └── PodroidService.kt # Foreground service, WakeLock, notifications-│ └── Actions: ACTION_START, ACTION_STOP | SSH port: 9922+│ └── PodroidService.kt # Foreground service, WakeLock, notification with boot stages+│ └── Actions: ACTION_START, ACTION_STOP│├── data/repository/-│ ├── SettingsRepository.kt # DataStore-backed settings (darkTheme, vmRam, vmCpus, storageSize, etc.)-│ ├── PortForwardRepository.kt # Port forward rules persistence-│ └── UpdateRepository.kt # GitHub release checker+│ ├── SettingsRepository.kt # DataStore Preferences (all settings)+│ ├── PortForwardRepository.kt # Port forward rules (Set<String> in DataStore)+│ └── UpdateRepository.kt # GitHub releases API checker│├── di/-│ └── AppModule.kt # Hilt module (empty - constructor injection only)+│ └── AppModule.kt # Hilt module (minimal — constructor injection used everywhere)│└── ui/├── navigation/- │ └── NavGraph.kt # Routes: SETUP, HOME, TERMINAL, SETTINGS- │ └── TerminalViewModel is scoped outside NavHost (survives navigation)+ │ └── NavGraph.kt # Routes: SETUP, HOME, TERMINAL, SETTINGS+ │ └── TerminalViewModel scoped OUTSIDE NavHost (survives screen navigation)│├── theme/- │ ├── Theme.kt # Material You (dynamic colors) + dark/light- │ ├── Color.kt # Purple80/Grey80/Cyan80 palette + status colors- │ └── Type.kt # Typography (default Material 3)+ │ ├── Theme.kt # Material You dynamic colors + dark/light+ │ ├── Color.kt # Purple80/Grey80/Cyan80 + status colors+ │ └── Type.kt # Default Material 3 typography+ │+ ├── HapticManager.kt # Centralized haptics: extraKeyPress, longPressMenu, bell, error│└── screens/+ ├── setup/+ │ ├── SetupScreen.kt # 3-page HorizontalPager: Storage / VM config+SSH / Downloads+ │ └── SetupViewModel.kt # completeSetup() → DataStore, notification permission request+ │├── home/- │ ├── HomeScreen.kt # Start/Stop VM, restart, open terminal, update dialog- │ └── HomeViewModel.kt # checkForUpdate(), startPodroid(), stopVm(), restartVm()+ │ ├── HomeScreen.kt # Start/Stop/Restart VM, open terminal, update dialog, AdaptiveContainer+ │ ├── HomeViewModel.kt # checkForUpdate(), startPodroid(), stopVm(), restartVm()+ │ └── AnimatedBootProgress.kt # Rotating arc Canvas + boot stage text (replaces CircularProgressIndicator)│├── terminal/- │ ├── TerminalScreen.kt # Termux TerminalView + extra keys bar, layout listener, auto keyboard- │ └── TerminalViewModel.kt # TerminalSession with podroid-bridge subprocess, mouse support+ │ ├── TerminalScreen.kt # TerminalView composable, extra keys bar, focus observer, pushSize+ │ ├── TerminalViewModel.kt # Session wiring, CSI keys, focus events, font/theme, forceUpdateSizeFromView+ │ ├── ExtraKey.kt # sealed KeyAction + JSON serde via ExtraKeySerde+ │ ├── DefaultKeyLayouts.kt # Built-in layouts: minimal, full (nvim/shell)+ │ └── QuickSettingsDrawer.kt # Bottom-sheet: font size, theme, font, extras toggle, haptics│├── settings/- │ ├── SettingsScreen.kt # Sections: Terminal → VM Resources → Network → Appearance → Diagnostics → About- │ └── SettingsViewModel.kt # Port forward CRUD, VM reset, console log export+ │ ├── SettingsScreen.kt # Sections: VM Resources / Network / Appearance / Diagnostics / About+ │ │ # Terminal settings moved to QuickSettingsDrawer (NOT here)+ │ └── SettingsViewModel.kt # Port forward CRUD, VM reset, console log export│- └── setup/- ├── SetupScreen.kt # 3-page pager: Storage size, VM config + SSH, Downloads sharing- └── SetupViewModel.kt # completeSetup() saves to DataStore, emits notification permission request-```--### app/src/main/res/-```-├── AndroidManifest.xml # INTERNET, WAKE_LOCK, VIBRATE, FOREGROUND_SERVICE, POST_NOTIFICATIONS-├── drawable/ # ic_vm_notification.xml, ic_stop.xml-├── mipmap-anydpi/ # App icons (ic_launcher.xml)-├── values/ # strings.xml, colors.xml, themes.xml-└── xml/- ├── file_paths.xml # FileProvider paths- ├── backup_rules.xml # Full backup rules- └── data_extraction_rules.xml # Android 12+ extraction rules+ └── components/+ └── AdaptiveContainer.kt # WindowSizeClass-based max-width wrapper (tablet/foldable)```### Assets (app/src/main/assets/)```-├── vmlinuz-virt # Linux kernel (built by docker-build-initramfs.sh)-├── initrd.img # Alpine initramfs with Podman (~71MB, built by docker-build-initramfs.sh)-├── qemu/ # QEMU BIOS/firmware files-├── colors/ # 114 terminal color schemes (.properties files)-│ └── dracula.properties, nord.properties, gruvbox-dark.properties, etc.-└── fonts/ # 13 curated terminal fonts (.ttf files)+├── vmlinuz-virt # Linux kernel (MUST match modules in initrd.img — same rootfs-builder stage)+├── initrd.img # Alpine initramfs (~71MB compressed)+├── qemu/+│ ├── efi-virtio.rom+│ └── keymaps/+├── colors/ # 114 terminal color schemes (.properties files)+└── fonts/ # 13 terminal fonts (.ttf)└── JetBrains-Mono.ttf, Fira-Code.ttf, CascadiaCode.ttf, etc.```### Native Libs (app/src/main/jniLibs/arm64-v8a/)```-├── libqemu-system-aarch64.so # QEMU executable (built by build-qemu-android.sh)-├── libslirp.so # SLIRP networking library-└── libpodroid-bridge.so # Terminal bridge (built by build-qemu-android.sh from podroid-bridge.c)+├── libqemu-system-aarch64.so # QEMU binary renamed .so for APK packaging+├── libslirp.so # SLIRP networking (soname patched from .so.0 via patchelf)+├── libpodroid-bridge.so # PTY↔serial bridge binary renamed .so for APK packaging+└── libtermux.so # Termux terminal JNI (custom-built with 16KB page alignment)```---@@ -162,179 +168,296 @@ Android App| Item | Value ||------|-------|-| QEMU binary | `libqemu-system-aarch64.so` in nativeLibDir |-| Kernel | `vmlinuz-virt` in filesDir |-| Initrd | `initrd.img` in filesDir |-| Storage image | `storage.img` in filesDir (ext4) |-| QMP socket | `qmp.sock` in filesDir |-| Serial console | ttyAMA0 → `serial.sock` in filesDir (unix socket, boot monitor + bridge) |-| Control channel | hvc0 → `ctrl.sock` in filesDir (virtio-console, resize signals) |-| QMP port (via socket) | 4444 (via unix socket) |-| VM IP | 10.0.2.15 |-| Default gateway | 10.0.2.2 |-| DNS (QEMU SLIRP) | 10.0.2.3 |-| Default DNS | 8.8.8.8, 1.1.1.1 |-| SSH host port (auto) | 9922 → VM:22 (Dropbear) |-| Storage sizes | 2, 4, 8, 16, 32, 64 GB |-| Default RAM | 512 MB | Range: 512MB – 4GB (512, 1024, 2048, 4096) |-| Default CPUs | 1 | Range: 1 – 8 (1, 2, 4, 6, 8) |+| QEMU binary | `libqemu-system-aarch64.so` in `nativeLibraryDir` |+| Kernel | `filesDir/vmlinuz-virt` |+| Initrd | `filesDir/initrd.img` |+| Storage image | `filesDir/storage.img` (ext4, sparse) |+| serial.sock | `filesDir/serial.sock` — ttyAMA0, single-client, boot monitor then bridge |+| ctrl.sock | `filesDir/ctrl.sock` — hvc0, bridge writes `RESIZE rows cols\n` |+| qmp.sock | `filesDir/qmp.sock` |+| VM IP | 10.0.2.15/24 (SLIRP) |+| Gateway | 10.0.2.2 |+| DNS (SLIRP) | 10.0.2.3 (unreliable on Android) + 8.8.8.8, 1.1.1.1 |+| SSH host port | 9922 → VM:22 (Dropbear, password "podroid") |+| Default RAM | 512 MB (range: 512–4096) |+| Default CPUs | 1 (range: 1, 2, 4, 6, 8) || Default font size | 20sp |-| Boot stages | "Starting QEMU..." → "Booting kernel..." → "Mounting storage..." → "Loading kernel modules..." → "Setting up overlay..." → "Configuring containers..." → "Waiting for network..." → "Network found" → "Almost ready..." → "Starting SSH..." → "Ready" |-| QEMU args | `-M virt,gic-version=3 -cpu max -accel tcg,thread=multi,tb-size=256` |-| Storage access mount | virtio-9p with `mount_tag=downloads` → `/mnt/downloads` in VM |-| Resize daemon | Background shell loop reads `RESIZE rows cols` from `/dev/hvc0`, calls `stty rows N cols M < /dev/ttyAMA0` |+| Default storage | 2 GB (range: 2–64 GB) |+| QEMU machine | `-M virt,gic-version=3 -cpu max -accel tcg,thread=multi,tb-size=256` |+| Kernel cmdline | `console=ttyAMA0 loglevel=1 quiet androidip=<ip> [ssh=1]` |----## DataStore Keys+## Boot Stage Strings (init-podroid → detectBootStage)-| Key | Type | Default | Description |-|-----|------|---------|-------------|-| `dark_theme` | Boolean | true | Dark mode |-| `vm_ram_mb` | Int | 512 | VM RAM in MB |-| `vm_cpus` | Int | 1 | VM CPU cores |-| `terminal_font_size` | Int | 20 | Font size in sp |-| `terminal_color_theme` | String | "default" | Selected color scheme name |-| `terminal_font` | String | "default" | Selected font name |-| `storage_gb` | Int | 2 | Persistent storage size |-| `storage_access_enabled` | Boolean | false | Downloads folder sharing |-| `setup_done` | Boolean | false | Initial setup completed |-| `ssh_enabled` | Boolean | false | SSH server in VM |-| `port_forwards` | Set\<String\> | {} | Serialized PortForwardRule |-| `dismissed_update_version` | String | null | Dismissed update version |+These exact strings are emitted by `init-podroid` and matched by `PodroidQemu.detectBootStage()`:++| String in serial output | Android UI label |+|------------------------|-----------------|+| `Initializing system...` | (no UI change — first phase 2 line) |+| `Loading kernel modules...` | "Loading kernel modules..." |+| `Waiting for network...` | (no match — intermediate) |+| `Network found` | "Network found" |+| `Configuring containers...` | "Configuring containers..." |+| `Starting SSH...` | "Starting SSH..." |+| `Almost ready...` | "Almost ready..." |+| `Ready!` | "Ready" → state = Running → autoStartBridge() |++Also detected: `Mounting storage...`, `Booting kernel...` (emitted by PodroidQemu itself, not init-podroid).++**Critical**: After `boot_stage "Ready!"`, init-podroid does `sleep 2` before starting the getty loop. This is intentional — gives the boot monitor time to read "Ready!" before the single-client serial.sock becomes available to the bridge.----## Port Forwarding System+## init-podroid Structure-### Format-```-"tcp:8080:80" → PortForwardRule(hostPort=8080, guestPort=80, protocol="tcp")+### Phase 1 (runs in initramfs as PID 1)+```bash+# Located AFTER the `if [ "$1" = "--main" ]; then ... fi` block (at end of file)+mount proc/sys/dev+depmod -a && modprobe virtio_blk # must load virtio_blk to get /dev/vda+find /dev/vda or /dev/vdb → PERSIST_DEV+mount -t ext4 PERSIST_DEV /mnt/persist # mkfs.ext4 if needed+mkdir -p /mnt/persist/upper /mnt/persist/work /mnt/overlay+mount -t overlay overlay -o lowerdir=/,upperdir=...,workdir=... /mnt/overlay+exec chroot /mnt/overlay /init --main+# FALLBACK (if overlay failed): exec /init --main ← runs without persistence```-### Service Presets (in SettingsScreen)-- **Pi-hole:** 5300→53(both), 8080→80(tcp)-- **Nginx:** 8080→80, 8443→443-- **Gitea:** 3000→3000, 2222→22-- **Grafana:** 3001→3000+**Critical bug to avoid**: The fallback at end of Phase 1 must NOT be `exec chroot /mnt/overlay /init --main` — if overlay failed, `/mnt/overlay` may not exist → kernel panic. Must be `exec /init --main`.++**Critical bug to avoid**: vmlinuz-virt and modules in initrd.img MUST come from the SAME rootfs-builder Docker stage. The Dockerfile copies vmlinuz from `rootfs-builder /boot/vmlinuz-virt` (NOT from the netboot downloader stage). Mismatched kernel/modules = `modprobe virtio_blk` silently skipped = no block device = no storage mount = kernel panic.-### Runtime Management-- At VM start: rules passed as QEMU `-netdev hostfwd` args-- At runtime: QMP `hostfwd_add`/`hostfwd_remove` via `human-monitor-command`+### Phase 2 (`--main` flag, runs inside chroot overlay)+```bash+boot_stage "Initializing system..."+# mount proc/sys/devtmpfs/devpts/tmpfs/cgroup2+boot_stage "Loading kernel modules..."+# depmod + modprobe (virtio_net, virtio_blk, fuse, tun, veth, bridge, overlay, ...)+boot_stage "Waiting for network..."+# wait for eth0 with IP (loop), set up resolv.conf (8.8.8.8, 1.1.1.1)+boot_stage "Network found" or boot_stage "Network found" (after timeout)+boot_stage "Configuring containers..."+# sysctl, /etc/subuid, containers.conf, storage.conf, registries.conf+boot_stage "Starting SSH..." # only if ssh=1 in kernel cmdline+# dropbearkey + dropbear+boot_stage "Almost ready..."+# MOTD generation with internet check, bash profile + aliases+# resize daemon: background loop reads RESIZE from /dev/hvc0, calls stty on /dev/ttyAMA0+# write podroid-login wrapper: #!/bin/bash; cat /etc/motd; exec script -q -c 'exec /bin/bash --login' /dev/null+boot_stage "Ready!"+rm -f /run/boot_stage+sleep 2 # ← CRITICAL: let boot monitor read "Ready!" before bridge steals socket+while true; do+ /sbin/getty -n -l /usr/local/bin/podroid-login 0 ttyAMA0 xterm-256color+ sleep 1+done+```++### podroid-login (written by init-podroid at runtime)+```bash+#!/bin/bash+cat /etc/motd 2>/dev/null+exec /usr/bin/script -q -c 'exec /bin/bash --login' /dev/null+```+The `script` wrapper is required for nvim to work correctly — it allocates a proper PTY inside the serial terminal session.---## Terminal Architecture-### Current Design (Podroid-Bridge PTY)-QEMU serial console exposed as a Unix socket (`serial.sock`). A native bridge binary-(`libpodroid-bridge.so`) runs as the `TerminalSession` subprocess — Termux allocates a-real PTY for it. The bridge relays PTY ↔ serial socket bidirectionally with no filtering.-The bridge sets its PTY to raw mode via `cfmakeraw()` (VM's getty handles-echo/line editing). Window resize propagates via the PTY/SIGWINCH chain:-+### Data Flow```-TerminalView layout change- → TerminalView.updateSize() [uses renderer font metrics]- → TerminalSession.updateSize(cols, rows) [Termux JNI: ioctl TIOCSWINSZ on PTY master]- → SIGWINCH → podroid-bridge- → bridge reads new size via TIOCGWINSZ- → writes "RESIZE rows cols\n" to ctrl.sock- → VM resize daemon reads /dev/hvc0- → stty rows N cols M < /dev/ttyAMA0 [Linux kernel sends SIGWINCH to fg process group]- → nvim / htop / btop redraws correctly+Keyboard → TerminalView → TerminalSession.write() → PTY master fd+ ↓+ podroid-bridge stdin (PTY slave)+ ↓+ serial.sock → ttyAMA0 in VM+VM output → ttyAMA0 → serial.sock → bridge stdout → PTY slave → TerminalEmulator → TerminalView+Resize → TerminalView.updateSize() → TIOCSWINSZ on PTY → SIGWINCH → bridge+ → bridge reads TIOCGWINSZ+ → writes "RESIZE rows cols\n" to ctrl.sock+ → VM daemon reads /dev/hvc0+ → stty rows N cols M < /dev/ttyAMA0+ → Linux SIGWINCH to VM fg process group+Mouse → TerminalView touch handler → PTY → bridge → serial → VM```-Mouse tracking is fully supported: Termux TerminalView natively handles mouse events-(touch gestures, USB/Bluetooth mouse buttons and scroll). When TUI apps enable mouse-mode (CSI 1000h), mouse clicks and scrolls route to the PTY → bridge → serial → VM.+### PodroidQemu Key Methods-**Auto keyboard**: When TerminalScreen opens with VM running, the Android soft keyboard-is shown automatically via `InputMethodManager.showSoftInput()` so users can type immediately.+| Method | What it does |+|--------|-------------|+| `start(portForwards, ramMb, cpus, sshEnabled, androidIp)` | Launches QEMU process, starts boot monitor coroutine, 60s timeout fallback |+| `monitorBootSerial(proc)` | Reads serial.sock, writes console.log, calls detectBootStage() |+| `detectBootStage(text)` | Matches boot stage strings, sets _bootStage and _state |+| `releaseSerial()` | shutdownInput + shutdownOutput + close on bootSocket |+| `autoStartBridge()` | Posts to MainLooper, calls releaseSerial(), 500ms delay, creates TerminalSession |+| `createTerminalSession(client)` | Returns pre-started session or creates new one; sets sessionClientDelegate |+| `replayBootOutput(sess)` | Appends post-"Ready!" serial bytes to new emulator (so first screen isn't blank) |+| `cleanup()` | Cancels ioScope, kills session, deletes socket files |-### Socket Files (in filesDir)-| File | Purpose |-|------|---------|-| `serial.sock` | QEMU serial chardev (ttyAMA0) — bridge connects here for terminal I/O |-| `ctrl.sock` | QEMU virtio-console chardev (hvc0) — bridge writes `RESIZE rows cols\n` here |-| `qmp.sock` | QEMU QMP control socket |+### TerminalViewModel Key Patterns++**`forceUpdateSizeFromView(view)`**: Computes cols/rows from `Paint` metrics using `currentTypeface` and raw `terminalFontSize.value.toFloat()` (NO scaledDensity multiplication — matches TerminalView's internal path exactly). Must use `currentTypeface` not `Typeface.MONOSPACE` for custom fonts.++**`pushSizeNow()`**: Fires `v.updateSize()` immediately + at 300ms + 800ms. Called after font size changes and after closing QuickSettings.++**`forceUpdateSizeFromView` via pushSize in TerminalScreen**: Fires at 0/150/600/1500ms after layout change to outlast lazy layout settling.++**Focus events**: `TerminalScreen` installs `LifecycleEventObserver`. ON_RESUME → `sendFocusEvent(true)` → `\x1b[I`. ON_PAUSE → `sendFocusEvent(false)` → `\x1b[O`. Gated on DECSET 1004 via reflection on `mCurrentDecSetFlags`.++**Proxy sessionClient** (`proxySessionClient` in PodroidQemu): Delegates to `sessionClientDelegate`. Lets session be created at boot-complete time before UI exists. TerminalViewModel sets itself as delegate via `qemu.sessionClientDelegate = sessionClient`.++### Key Sequences (TerminalViewModel.viewClient.onKeyDown)-### Data Flow```-Keyboard → TerminalView → TerminalSession.write() → PTY master → bridge stdin → serial.sock → ttyAMA0-VM output → serial.sock → bridge stdout → PTY slave → TerminalSession → TerminalEmulator → TerminalView-Resize → PTY TIOCSWINSZ → SIGWINCH → bridge → ctrl.sock → VM hvc0 daemon → stty → SIGWINCH in VM-Mouse → TerminalView (touch/mouse) → sendMouseEventCode() → PTY → bridge → serial → VM+mod = 1 + (shift?1:0) + (alt?2:0) + (ctrl?4:0)+arrow(final): if mod==1 → "\x1b[$final" else → "\x1b[1;$mod$final"```-### CSI 6n / nvim Support-No CSI 6n filtering in the bridge. The shell (`set +o checkwinsize` in `/etc/profile`)-does not send cursor position queries. nvim's TUI initializes correctly.+| Key | Sequence |+|-----|----------|+| Shift+Tab | `\x1b[Z` |+| Ctrl+Left/Right | `\x1b[1;5D` / `\x1b[1;5C` |+| Shift+Up/Down | `\x1b[1;2A` / `\x1b[1;2B` |+| F1–F4 | `\x1bOP` … `\x1bOS` |+| F5–F12 | `\x1b[15~` … `\x1b[24~` |++**Bracketed paste**: `onPasteTextFromClipboard` calls `emu.paste(text)` — Termux wraps in `\x1b[200~…\x1b[201~` when DECSET 2004 is active.-### Boot Monitoring-`PodroidQemu` connects to `serial.sock` via `android.net.LocalSocket` and reads until-the "Ready" stage is detected (writing to `console.log`). `releaseSerial()` shuts-down the socket input/output and closes it so `podroid-bridge` can connect when-the user opens the terminal.+**Extra keys hold-to-repeat**: `KeyButton` composable uses `pointerInput + LaunchedEffect` — 400ms initial delay then 70ms → 30ms accelerating cadence. Only arrow keys flagged `repeatable = true`.++**CTRL/ALT sticky**: `extraCtrl` / `extraAlt` toggles on the extras bar. Consumed after any non-modifier key press.++----**Serial handoff timing**: QEMU serial socket (`server,nowait`) only serves one client-at a time. `releaseSerial()` uses `shutdownInput()` + `shutdownOutput()` + `close()`-to reliably interrupt the boot monitor's blocking read. `createSession()` sleeps 500ms-after `releaseSerial()` to let QEMU re-listen. The bridge binary also has a retry-loop (50 attempts × 200ms = 10s max) as defense in depth.+## podroid-bridge.c-### Extra Keys-ESC, TAB, CTRL (sticky), ALT (sticky),-arrows, HOME, END, PGUP, PGDN, F1-F12, -, /, |+- **Purpose**: Relay PTY (Termux-allocated) ↔ `serial.sock` (QEMU serial)+- **Arguments**: `bridge_exe serial_sock_path ctrl_sock_path`+- **STDERR silenced** immediately via `dup2(/dev/null, STDERR_FILENO)` — bridge runs as TerminalSession subprocess so stderr IS the PTY+- **`cfmakeraw()`** on own stdin (VM's getty handles echo/line editing)+- **serial.sock retry**: 50 attempts × 200ms = 10s max+- **ctrl.sock retry**: 50 × 100ms = 5s max; lazy reconnect on each SIGWINCH if not yet connected+- **`filter_queries()`**: Intercepts `ESC[18t` / `ESC[19t` (xterm window size queries from busybox `less`), responds locally with fake size, strips bytes — prevents garbage in terminal output+- **`send_resize()`**: On SIGWINCH, reads new size via `TIOCGWINSZ`, writes `RESIZE rows cols\n` to ctrl.sock+- **select timeout**: 50ms (allows SIGWINCH handling without blocking)----## init-podroid (VM init script)--### Phase 1 (Early init, before overlay)-- Mount proc/sys/dev-- Load virtio modules (virtio_pci, virtio_net, virtio_blk)-- Detect persistent storage device (vda/vdb)-- Mount ext4, create overlayfs (lower=/, upper=/mnt/persist/upper, work=/mnt/persist/work)-- `chroot /mnt/overlay /init --main`--### Phase 2 (--main flag)-- Mount filesystems (proc, sys, devtmpfs, devpts, tmpfs)-- busybox --install -s-- Network setup (SLIRP: 10.0.2.15/24, gateway 10.0.2.2, DNS 10.0.2.3)-- Downloads folder mount via 9p virtio-- Container config (sysctl, /etc/subuid, containers.conf, storage.conf, registries.conf, crun.conf)-- SSH setup (Dropbear): RSA host key via `dropbearkey`, password "podroid"-- MOTD with VM info-- Resize control daemon: background loop reads `RESIZE rows cols` from `/dev/hvc0`,- calls `stty rows N cols M < /dev/ttyAMA0`-- `podroid-login` wrapper for getty-- getty on ttyAMA0+## Dockerfile (Unified Multi-Stage)++### Stages+```+downloader — downloads Alpine netboot tarball (currently unused for vmlinuz — see CRITICAL below)+rootfs-builder — --platform=linux/arm64/v8, installs all Alpine packages via apk, copies init-podroid as /init+packer — cpio + gzip the rootfs into initrd.img; copies vmlinuz from rootfs-builder+qemu-builder — debian:bookworm + NDK r27c, cross-compiles QEMU 11.0.0-rc2 + podroid-bridge + deps+final — scratch stage, collects all output artifacts+```++### CRITICAL: vmlinuz source+The packer stage copies `vmlinuz-virt` from **`rootfs-builder /boot/vmlinuz-virt`** (the kernel installed by `apk add linux-virt`). This ensures vmlinuz and `/lib/modules/$KVER/` are the same version. **Never copy vmlinuz from the downloader/netboot tarball** — that is a different Alpine release and causes a kernel/modules version mismatch → `modprobe virtio_blk` silently fails → no block device → kernel panic.++### QEMU Build Details+- NDK r27c, API 28 sysroot+- Dependencies (static): pcre2, libffi, glib 2.82.5, pixman 0.44.2, libattr, libucontext+- **libucontext shim**: Android Bionic lacks `ucontext.h` → built from kaniini/libucontext; header shim remaps `getcontext/swapcontext/etc.` to libucontext functions+- **`--with-coroutine=ucontext`**: Required for ARMv9.2 PAC (Android 15+ Tensor devices) — avoids SIGILL from siglongjmp across alternate signal stacks+- **librt optional** patch: Bionic includes librt functions in libc+- **`st_*_nsec` undef** patch: Android's `sys/stat.h` macros clash with 9p struct fields+- **patchelf**: libslirp soname patched from `libslirp.so.0` → `libslirp.so`++### 16KB Page Alignment+All native libs must have `p_align >= 16384`. Enforced via `-Wl,-z,max-page-size=16384` everywhere. Required for Android devices with 16KB system pages. Verified by Python ELF parser in `build-all.sh`.++### VM Rootfs Packages (Alpine 3.23 aarch64)+```+linux-virt bash busybox busybox-extras ttyd podman podman-remote+netavark aardvark-dns fuse-overlayfs slirp4netns iptables ip6tables+shadow-uidmap ca-certificates crun curl e2fsprogs util-linux openrc+dropbear ncurses-terminfo-base musl-locales+```---## Build Commands```bash-# Build initramfs (requires Docker with multi-arch)-./docker-build-initramfs.sh+# Build initramfs (Docker required, ~3min first time, cached after)+./build-all.sh initramfs+# → app/src/main/assets/vmlinuz-virt + initrd.img-# Build QEMU + bridge (requires Docker)-./build-qemu-android.sh+# Build QEMU + bridge (Docker, ~30min first time)+./build-all.sh qemu+# → app/src/main/jniLibs/arm64-v8a/{libqemu-system-aarch64.so,libslirp.so,libpodroid-bridge.so}+# → app/src/main/assets/qemu/-# Build Termux terminal lib with 16KB page alignment (requires NDK)-./build-termux-android.sh+# Build Termux JNI lib (local NDK)+./build-all.sh termux+# → app/src/main/jniLibs/arm64-v8a/libtermux.so# Build APK./gradlew assembleDebug-# Uninstall + install-adb uninstall com.excp.podroid.debug && adb install -r app/build/outputs/apk/debug/app-debug.apk+# Uninstall + install (debug package)+adb uninstall com.excp.podroid.debug+adb install -r app/build/outputs/apk/debug/app-debug.apk++# Fast bridge rebuild (without full Docker QEMU build)+NDK=$HOME/Android/Sdk/ndk/$(ls ~/Android/Sdk/ndk/ | tail -1)+CC=$NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android28-clang+$CC --sysroot=$NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot \+ -target aarch64-linux-android28 -fPIE -pie -Wl,-z,max-page-size=16384 \+ podroid-bridge.c -o app/src/main/jniLibs/arm64-v8a/libpodroid-bridge.so+./gradlew :app:installDebug++# Full rebuild + deploy+./build-all.sh all++# Automated boot test+./build-all.sh test+```++**Workflow**:+- `init-podroid` changed → `./build-all.sh initramfs` → `gradlew assembleDebug` → `adb install`+- Kotlin/Java only → `gradlew assembleDebug` → `adb install`+- `podroid-bridge.c` changed → fast bridge rebuild above → `adb install`+- Check boot: `adb shell run-as com.excp.podroid.debug cat files/console.log`++---++## DataStore Keys (SettingsRepository)++| Key | Type | Default | Description |+|-----|------|---------|-------------|+| `dark_theme` | Boolean | true | Dark mode |+| `vm_ram_mb` | Int | 512 | VM RAM (512/1024/2048/4096 MB) |+| `vm_cpus` | Int | 1 | VM CPUs (1/2/4/6/8) |+| `terminal_font_size` | Int | 20 | Font size (sp, raw — no scaledDensity) |+| `terminal_color_theme` | String | "default" | Color scheme name (maps to assets/colors/*.properties) |+| `terminal_font` | String | "default" | Font name (maps to assets/fonts/*.ttf) |+| `storage_gb` | Int | 2 | Persistent storage size (GB) |+| `storage_access_enabled` | Boolean | false | Downloads sharing via virtio-9p |+| `setup_done` | Boolean | false | Initial setup completed |+| `ssh_enabled` | Boolean | false | Dropbear SSH in VM |+| `port_forwards` | Set\<String\> | {} | `"tcp:8080:80"` format |+| `dismissed_update_version` | String | "" | Last dismissed update version |++---++## Port Forwarding++```+PortForwardRule(hostPort=8080, guestPort=80, protocol="tcp")+Serialized as: "tcp:8080:80"```-**Workflow**: If initramfs modified → `docker-build-initramfs.sh` → `gradlew assembleDebug` →-`adb uninstall com.excp.podroid.debug && adb install -r`. If only APK code modified → just the-last three steps.+- **At boot**: passed as QEMU `-netdev user,hostfwd=tcp::8080-:80` args+- **At runtime**: QMP `human-monitor-command hostfwd_add` / `hostfwd_remove`+- **SSH preset**: always forwarded as `tcp::9922-:22` when `sshEnabled = true`+- **Service presets** (SettingsScreen): Pi-hole (5300→53, 8080→80), Nginx (8080→80, 8443→443), Gitea (3000→3000, 2222→22), Grafana (3001→3000)+- **Pi-hole DNS**: host port 5300 used because Android blocks ports < 1024---@@ -342,64 +465,81 @@ last three steps.| Permission | Purpose ||------------|---------|-| INTERNET | SLIRP networking, QMP socket, GitHub API |-| ACCESS_NETWORK_STATE | Get device IP |-| WAKE_LOCK | Keep CPU awake during VM run |-| VIBRATE | Terminal bell feedback |-| FOREGROUND_SERVICE | Host QEMU process |-| FOREGROUND_SERVICE_SPECIAL_USE | QEMU "emulation" subtype |-| POST_NOTIFICATIONS | Android 13+ notification permission |-| MANAGE_EXTERNAL_STORAGE | Downloads folder sharing via virtio-9p |+| `INTERNET` | SLIRP, QMP socket, GitHub API |+| `ACCESS_NETWORK_STATE` | Get device IP for display |+| `WAKE_LOCK` | Keep CPU alive during VM |+| `VIBRATE` | Terminal bell, haptic feedback |+| `FOREGROUND_SERVICE` | Host QEMU process |+| `FOREGROUND_SERVICE_SPECIAL_USE` | QEMU "emulation" subtype |+| `POST_NOTIFICATIONS` | Android 13+ notification |+| `MANAGE_EXTERNAL_STORAGE` | Downloads sharing via virtio-9p |----## Design Patterns--- **Single Activity:** Compose Navigation with NavHost-- **Hilt:** Constructor injection, no @Provides needed-- **DataStore:** Preferences DataStore for all settings-- **StateFlow:** All UI state exposed as StateFlow-- **Reflection:** `TerminalView.mTermSession` and `mEmulator` set directly via reflection-- **Coroutines:** IO dispatcher for QEMU I/O, Main for UI updates-- **Sealed Classes:** VmState for lifecycle states-- **Persistence:** Two-layer (DataStore for config, ext4 image for VM data)+## Design Patterns & Quirks++### Architecture+- **Single Activity**: Compose Navigation with NavHost+- **TerminalViewModel scoped outside NavHost**: Survives navigation between screens; session persists+- **Proxy sessionClient**: `proxySessionClient` in PodroidQemu delegates to `sessionClientDelegate`; lets session be pre-created at boot before UI attaches+- **Reflection**: `TerminalView.mTermSession`, `mEmulator`, `TerminalEmulator.mCurrentDecSetFlags`, `mapDecSetBitToInternalBit` — all accessed reflectively (Termux AAR private fields)+- **VmState flow**: Idle → Starting → Running → Stopped/Error; service/UI observe via StateFlow++### Known Quirks+- **QEMU + bridge packaged as `.so`**: ELF executables renamed to `.so` for APK packaging; `nativeLibraryDir` extraction still works+- **libslirp soname patched**: `libslirp.so.0` → `libslirp.so` via patchelf (Android linker needs exact match)+- **libtermux.so custom-built**: Termux prebuilt uses 4KB pages; rebuilt with `-Wl,-z,max-page-size=16384`+- **Root project name is "VirtuDroid"**: In `settings.gradle.kts`+- **Room declared but unused**: DataStore used instead+- **Downloads sharing via 9p**: `msize=1048576,cache=loose,noatime` — 128× fewer round-trips vs default 8KB msize+- **QEMU DNS forwarder (10.0.2.3) unreliable on Android**: init-podroid uses 8.8.8.8 + 1.1.1.1 directly+- **No ICMP in SLIRP**: `ping` doesn't work inside VM (QEMU SLIRP limitation)+- **forceUpdateSizeFromView must NOT multiply by scaledDensity**: TerminalView passes raw int textSize to Paint.setTextSize; our computation must match or TUI apps render in wrong grid+- **Bridge stderr silenced**: bridge runs as TerminalSession subprocess, its stderr IS the PTY; any write would bleed into the terminal. Never add `fprintf(stderr, ...)` to podroid-bridge.c+- **seenActive flag in PodroidService**: Prevents premature wakelock release on service start before VM reaches Running state---## Common Tasks Reference-### Add a new setting-1. Add key to `SettingsRepository.kt` (DataStore key + Flow)-2. Add UI in `SettingsScreen.kt` (Slider/Switch/etc.)-3. Add setter in `SettingsViewModel.kt`+### Rebuild initramfs (init-podroid changed)+```bash+./build-all.sh initramfs && ./gradlew assembleDebug && adb uninstall com.excp.podroid.debug; adb install -r app/build/outputs/apk/debug/app-debug.apk+```-### Add a new port forward preset-1. Add to `servicePresets` list in `SettingsScreen.kt`+### Check VM console output+```bash+adb shell run-as com.excp.podroid.debug cat files/console.log+```-### Add a new boot stage detection-1. Add case in `PodroidQemu.detectBootStage()`+### Add a new boot stage+1. Add `boot_stage "My stage..."` at correct position in `init-podroid`+2. Add match in `PodroidQemu.detectBootStage()`+3. Rebuild initramfs-### Modify QEMU arguments-1. Edit `PodroidQemu.buildCommand()`+### Add a setting+1. Add DataStore key + Flow in `SettingsRepository.kt`+2. Add UI in `SettingsScreen.kt` (Slider/Switch)+3. Add setter in `SettingsViewModel.kt`+4. Pass to `PodroidQemu.start()` if VM-time setting-### Modify the terminal bridge-1. Edit `podroid-bridge.c`-2. Rebuild with `./build-qemu-android.sh` (bridge is compiled alongside QEMU)+### Add a port forward preset+1. Add to `servicePresets` list in `SettingsScreen.kt`-### Add a terminal color theme+### Add terminal color theme1. Add `.properties` file to `app/src/main/assets/colors/`-2. Theme appears automatically in the Settings picker dialog+2. Appears automatically in QuickSettingsDrawer picker-### Add a terminal font-1. Add `.ttf` file to `app/src/main/assets/fonts/`-2. Font appears automatically in the Settings picker dialog+### Add terminal font+1. Add `.ttf` to `app/src/main/assets/fonts/`+2. Appears automatically in QuickSettingsDrawer picker-### Add a new VM control signal (e.g. beyond RESIZE)-1. Add a new message format to `podroid-bridge.c` (write to ctrl.sock)-2. Add a new case to the resize daemon in `init-podroid` (read from `/dev/hvc0`)+### Modify QEMU arguments+1. Edit `PodroidQemu.buildCommand()`-### Modify VM init sequence-1. Edit `init-podroid` shell script+### Add a new VM control channel message+1. Add write to `ctrl.sock` in `podroid-bridge.c`+2. Add handler in the resize daemon loop in `init-podroid` (reads from `/dev/hvc0`)---@@ -415,159 +555,31 @@ last three steps.| Hilt | 2.59.2 || Coroutines | 1.9.0 || DataStore | 1.2.1 |-| Termux terminal | v0.118.1 |+| Termux terminal-view | v0.118.1 (JitPack) || Lifecycle | 2.9.0 || Activity Compose | 1.10.1 |-| Room | 2.8.4 (declared but **NOT USED**) |--## Build Scripts--### docker-build-initramfs.sh-- Uses multi-stage Dockerfile-- Downloads Alpine 3.23 aarch64 netboot + virt ISO-- Installs packages via qemu-user-static on x86_64-- Outputs: `app/src/main/assets/{vmlinuz-virt,initrd.img}` (~71MB)--### build-qemu-android.sh-- Reads `podroidQemuVersion` from `gradle.properties`-- Builds via `Dockerfile.qemu`-- Compiles podroid-bridge alongside QEMU-- Outputs to `app/src/main/jniLibs/arm64-v8a/` and `app/src/main/assets/qemu/`--### build-termux-android.sh-- Clones Termux v0.118.1 from GitHub-- Compiles `libtermux.so` with **16KB page alignment** (`-Wl,-z,max-page-size=16384`)-- Verifies alignment via Python ELF parsing-- Required because Android may use 16KB page devices--## Dockerfile - VM Rootfs Packages+| WindowSizeClass | material3-adaptive (Compose BOM) |+| Room | 2.8.4 (declared, NOT used) |-Installed via `apk` in Alpine aarch64:-```-linux-virt, busybox, ttyd, podman, netavark, aardvark-dns,-fuse-overlayfs, slirp4netns, shadow-uidmap, ca-certificates,-crun, curl, e2fsprogs, util-linux, openrc, dropbear,-ncurses-terminfo-base, musl-locales-```--## ProGuard Rules (app/proguard-rules.pro)--Keeps Termux reflection targets:-- `TerminalView.mTermSession` — set directly in TerminalScreen to wire the session-- `TerminalView.mEmulator` — set directly in TerminalScreen to wire the display emulator--## 16KB Page Alignment Requirement--All native libs (QEMU, slirp, termux.so) must have `p_align >= 16384` in ELF headers. This is verified by Python scripts in the build scripts. Reason: some Android devices use 16KB system pages.--## Terminal Resize Sequence--When the view layout changes (keyboard open/close, rotation):-1. `addOnLayoutChangeListener` calls `TerminalView.updateSize()` (uses renderer's exact font metrics)-2. TerminalView calculates cols/rows, calls `TerminalSession.updateSize(cols, rows)`-3. Termux JNI: `ioctl(pty_master_fd, TIOCSWINSZ)` → SIGWINCH to `podroid-bridge`-4. Bridge: `ioctl(STDIN, TIOCGWINSZ)` → writes `RESIZE rows cols\n` to `ctrl.sock`-5. VM daemon reads `/dev/hvc0` → `stty rows N cols M < /dev/ttyAMA0`-6. Linux kernel sends SIGWINCH to the foreground process group of ttyAMA0--No stdin injection. No debounce. nvim/htop/btop resize automatically.--## Settings.gradle.kts--- **Root project name:** `VirtuDroid`-- **App module:** `:app`-- **Repositories:** google, mavenCentral, **JitPack** (for Termux)-- **Toolchain:** foojay-resolver-convention 1.0.0--## Dockerfile.qemu - QEMU Build Details--### Build Dependencies-- NDK r27c (Android API 28) — QEMU builds against API 28 sysroot to avoid symbols not available in Android 9-11 (like copy_file_range)-- Cross-compile from debian:bookworm-- Dependencies: pcre2, libffi, glib 2.82.5, pixman 0.44.2, libattr, **libucontext**--### libucontext Shim-Android Bionic lacks proper `ucontext.h`. Built from [kaniini/libucontext](https://github.com/kaniini/libucontext). Provides `getcontext`, `swapcontext`, etc. A header shim remaps the standard functions to the libucontext versions.+----### QEMU Patches Applied-1. **librt optional** — Bionic has librt functions in libc, not a separate library-2. **memfd_create shim** — `qemu_shm_alloc` uses `syscall(__NR_memfd_create)` instead of `shm_open` (API 28+)-3. **libattr stub** — `libattr = declare_dependency()` bypasses pkg-config detection (xattr in Bionic's libc)-4. **st_\*_nsec undef** — Undefines `st_atime_nsec` etc. macros from Android's sys/stat.h that clash with 9p struct fields+## ProGuard-### QEMU Configure Flags-```---enable-tcg --enable-kvm --enable-system --enable-slirp --enable-virtfs --enable-pie---disable-werror --disable-docs --disable-gtk --disable-sdl --disable-opengl --disable-vnc---disable-capstone --disable-seccomp --disable-libiscsi --disable-libnfs --disable-libssh---disable-curl --disable-spice --disable-vde --disable-linux-io-uring---with-coroutine=ucontext ← REQUIRED: PAC fix for Android 15+ on Tensor devices-```--### podroid-bridge Build (in Dockerfile.qemu)-```-${CC} ${CFLAGS} -fPIE -pie ${LDFLAGS} podroid-bridge.c -o podroid-bridge-cp podroid-bridge libpodroid-bridge.so-```-Same NDK, same CFLAGS/LDFLAGS (16KB page alignment enforced). Outputs `libpodroid-bridge.so`.+`app/proguard-rules.pro` keeps Termux reflection targets:+- `TerminalView.mTermSession`+- `TerminalView.mEmulator`-### podroid-bridge Responsibilities-- Connect to `serial.sock` (QEMU serial unix socket)-- Allocate PTY via `forkpty()` (Termux provides the PTY master)-- Set `cfmakeraw()` on PTY slave (VM's getty handles echo/line editing)-- Relay bidirectionally: PTY ↔ serial.sock-- No filtering — all escape sequences pass through unmodified-- On SIGWINCH: read PTY size via `TIOCGWINSZ`, write `RESIZE rows cols\n` to `ctrl.sock`--### PAC (Pointer Authentication) Fix-Android 15+ on Pixel (Tensor) uses ARMv9.2 with PAC. Default QEMU sigaltstack coroutine calls `siglongjmp` across alternate signal stacks — this fails PAC validation and raises SIGILL. Fix: `--with-coroutine=ucontext` uses `swapcontext` instead.+----### Output Artifacts-```-app/src/main/jniLibs/arm64-v8a/-├── libqemu-system-aarch64.so # QEMU binary renamed to .so for APK packaging-├── libslirp.so # SLIRP networking (soname patched from .so.0)-└── libpodroid-bridge.so # Terminal bridge binary renamed to .so for APK packaging--app/src/main/assets/qemu/-├── efi-virtio.rom # VirtIO EFI ROM-└── keymaps/ # QEMU keyboard maps-```+## Pending Work (as of 2026-04-22)-### 16KB Page Alignment-All artifacts must have `p_align >= 16384`. Enforced via `LDFLAGS=-Wl,-z,max-page-size=16384` in both NDK toolchain and QEMU link step. Verified by Python ELF parser in build script.--## test-deploy.sh--Automated build → install → boot test script:-1. Check ADB device connected-2. Optionally rebuild initramfs-3. Build debug APK with Gradle-4. Install via `adb install -r`-5. Force stop app + delete `storage.img` (clean state)-6. Launch app via `am start`-7. Wait for user to press "Start VM"-8. Poll `console.log` for boot completion (timeout 60s)-9. Run validation checks (banner, IP, persistent, internet, Ready!, kernel modules, network)-10. Detect kernel panics/crashes--## Known Quirks--- **Room declared but unused** — DataStore is used for persistence instead-- **KSP version differs from Kotlin** — Kotlin 2.2.21, KSP 2.3.6-- **QEMU packaged as `.so`** — Actually an ELF executable renamed from binary to `.so` for Android packaging-- **podroid-bridge packaged as `.so`** — Same trick: PIE executable renamed to `.so` for APK extraction-- **Project name in Gradle is "VirtuDroid"** — `rootProject.name` in settings.gradle.kts-- **SLIRP soname patched** — `libslirp.so.0` → `libslirp.so` via patchelf for APK compatibility-- **libtermux.so custom-built** — Termux's prebuilt uses 4KB pages; rebuilt with 16KB alignment via `build-termux-android.sh`-- **Boot monitor connects to serial.sock first** — PodroidQemu reads boot output from serial.sock until "Ready", then `releaseSerial()` uses `shutdownInput()`+`close()` to interrupt blocking read; bridge has 50-retry connect loop as defense in depth-- **releaseSerial() sets bootStage="Ready"** — With persistent overlay the VM boots faster than the boot monitor can detect boot completion strings; `releaseSerial()` unconditionally marks boot as "Ready" when the terminal takes over-- **Some tui apps hangs on Podroid** — Works inside tmux or by using SSH .--## GitHub--- **Repo:** github.com/ExTV/Podroid-- **Releases API:** https://api.github.com/repos/ExTV/Podroid/releases/latest-- **Update check:** `UpdateRepository.checkForUpdate()` compares tag_name vs BuildConfig.VERSION_NAME+### Next Feature: Container Hub+Full container management screen — SSH into VM at `127.0.0.1:9922`, run `podman ps`, one-tap deploy from a catalog of services (Pi-hole, Vaultwarden, code-server, Gitea, Jellyfin, Uptime Kuma, Filebrowser, Nginx, Grafana). Requires JSch dependency.----+### Other TODOs+- **OpenRC integration**: Replace manual init-podroid boot with proper OpenRC service scripts (fixes `rc-service` and docker socket compatibility)+- **Pin Dockerfile packages**: Add version pins to prevent reproducibility breaks+- **DNS configurable**: Currently hardcoded 8.8.8.8 + 1.1.1.1; add settings UI+- **Overlay mount validation**: Detect and surface overlay failures with actionable error+- **Terminal title → TopAppBar**: Wire `onTitleChanged()` to update app bar from OSC sequences+- **Custom font loading**: Allow users to load their own .ttf files (GitHub issue #5)