# Kaleido ## Working rules - Ask clarifying questions before proceeding when more information is needed. Otherwise make reasonable decisions and complete the authorized work. - This is a real native Android TV Plex client: Kotlin, Jetpack Compose, Media3/ExoPlayer. Preserve working Plex functionality; do not substitute mock content or prototype playback. - The authorized test device is the onn at **192.168.50.195:5555**, package **tv.kaleido.app**, activity **.MainActivity**. Always specify the ADB serial. Do not modify its launcher, accessibility services, other apps, or other devices. - `.env` contains `PLEX_SERVER_URL` and `PLEX_TOKEN` for local testing. Never print, commit, or embed credentials in source, resources, APKs, or logs. Keep `.env`, signing keys, toolchains, and private evidence ignored. - Use the existing encrypted session. `scripts/device.py seed` provisions an installed **debug** build only when needed; the app encrypts and deletes its bootstrap file. Never clear app data or sign out just to reset a test. ## UI and architecture - **Home:** large cinematic hero with playback/information actions and integrated landscape Continue Watching. Do not replace it with the compact section preview. - **Movies:** compact preview/backdrop follows focused posters; recent releases and movie recommendations lead. **TV:** episode-first layout with wider next-episode thumbnails, new seasons and new episodes. Keep these destinations visibly distinct. - Both sections retain a dedicated, filtered/sorted **A–Z poster grid**. Primary tabs activate on focus. Use neutral near-black chrome, artwork-led color, restrained controls and stable card bounds. Inspect actual TV screenshots and D-pad behavior after UI changes. - `KaleidoViewModel.kt`: navigation, async loading and section caches. `PlexApi.kt` / `Models.kt`: Plex transport and parsing. `FocusedBrowse.kt`, `BrowseBackdrop.kt`, `BrowseScreens.kt`, `Theme.kt`: browsing/focus/design. `Playback.kt`: controller, negotiation and progress. `PlayerControls.kt` / `PlaybackExtras.kt`: controls, options and post-play. `SecureSession.kt`: Android Keystore persistence. `AppUpdater.kt`: repository updates. ## Build and device setup Run from the repository root in PowerShell. `Build.ps1` configures the local JDK 17, Gradle 8.13 and SDK under `.tools/`; do not replace the toolchain unnecessarily. Builds/ADB may require sandbox escalation. ```powershell $KaleidoAdb = 'C:\Users\Elijah\Desktop\platform-tools\adb.exe' $KaleidoDevice = '192.168.50.195:5555' $KaleidoPython = 'C:\Users\Elijah\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' $env:PYTHONIOENCODING = 'utf-8' & $KaleidoAdb -s $KaleidoDevice get-state .\Build.ps1 -Test # Debug APK, unit tests, lint .\Build.ps1 -Release -Test # Optimized release APK, unit tests, lint & $KaleidoAdb -s $KaleidoDevice install -r app/build/outputs/apk/debug/app-debug.apk ``` Install `app/build/outputs/apk/release/app-release.apk` instead for performance/final visual review. Debug and release share the private local signing key, so `install -r` preserves data. ## Testing suite Use `& $KaleidoPython` before the Python commands below. Run only checks relevant to the change; **never run competing device/UI tests in parallel**. Live playback tests change real Plex progress and can change playback preferences. Restore a useful final state, normally the release build on Home. | Command | Purpose / required build | | --- | --- | | `scripts/verify_ui.py browse` | Home/Movies/TV, A–Z, focus restoration, live Plex PIN and cancellation; debug or release | | `scripts/verify_ui.py player` | Actual playback, scrub preview, track/options menus, speed/mode, hide/show/exit; **debug** | | `scripts/repro_runtime.py sections` | Cold-start tab-switch blank-page regression; debug or release | | `scripts/repro_runtime.py browse` | Horizontal bounds and frame pacing; **optimized release with profile compilation** | | `scripts/repro_runtime.py controls` | One-press Back, OK reveal, timed hide and exit; **debug** | | `scripts/repro_runtime.py episode` | Next-episode replacement/crash regression; **debug** | | `scripts/repro_runtime.py postplay` | Natural ending → five-second countdown → next episode READY; **debug** | | `scripts/repro_runtime.py credits` | Visible Skip credits, season/related rows and cancellable countdown; **debug** | | `scripts/device.py screenshot ` | Capture to ignored `evidence/private/`; also supports `hierarchy`, `logs`, `launch`, `key` | | `scripts/profile_browse.py` | Targeted atrace investigation when navigation performance regresses | | `scripts/profile_home.py