All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m33s
- Credits and episode endings open Up Next: the video keeps playing in a top-left mini-player beside the next episode, season and related shows. Play next episode carries the only countdown; any remote press stops it. Left then OK on the video, or Back, returns to the credits. - Wait for the player's final timeline report before reloading Home, so Continue Watching reflects the episode just watched. - Remove the source label above Home's featured title. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
119 lines
15 KiB
Markdown
119 lines
15 KiB
Markdown
# 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 primary test device is the onn at **192.168.50.195:5555**, package **tv.kaleido.app**, activity **.MainActivity**. The user also authorized two weaker devices for performance testing: a Fire TV Stick 4K (Fire OS 8, 32-bit) at **192.168.50.146:5555** and a TCL Smart TV Pro (MT5896, slowest GPU) at **192.168.50.200:5555**. Scripts target the onn unless `KALEIDO_DEVICE` names another serial. Always specify the ADB serial. Do not modify any device's launcher, accessibility services (the onn runs Luma's Home-button service; Button Mapper was removed at the user's request on 2026-10-29; any service makes Compose do semantics work), settings, or other apps. The TCL's network ADB link drops intermittently; `device.py` reconnects and retries.
|
||
- `.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. Entering the rows compacts it into a Silo-style preview of the focused card (its own image, top-right); Up/Back restores the hero.
|
||
- **Movies:** the same Silo-style preview 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' rows visibly distinct. The optional artwork colour wash is baked into the preview backdrop bitmap.
|
||
- 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. **Never run competing device/UI tests in parallel.**
|
||
|
||
**Test in tiers; don't run every suite for every change.** Each device script cold-starts Kaleido, waits for playback and real timers, and dumps the UI per check, so a full pass takes 30+ minutes.
|
||
|
||
1. **Every change:** `.\Build.ps1 -Test` (compile, JVM unit tests, lint; about a minute). Put pure logic (ordering, parsing, fingerprints, countdown rules) in unit-testable functions with JVM tests instead of proving it on the TV.
|
||
2. **UI or device behaviour changed:** run only the one or two scripts for the area touched (map below), plus a screenshot of the changed screen. One script is usually 1–4 minutes.
|
||
3. **Before a release, or after broad navigation/playback/startup changes:** the full set: `verify_ui.py browse` and `player`, `repro_runtime.py controls episode postplay credits sections`, `verify_player_features.py`, `verify_settings.py`, then the release build with `repro_runtime.py browse` for frame pacing.
|
||
|
||
Area → checks: Home/Movies/TV rows, focus, details Back → `verify_ui.py browse` · player bar, menus, scrubbing → `verify_ui.py player` · previous/next episode, auto-skip, server picker, cross-device refresh → `verify_player_features.py <phase>` · post-play/autoplay/credits → `repro_runtime.py postplay` or `credits` · Settings rows/dialogs → `verify_settings.py` · details/cast → `verify_details_layout.py` / `verify_movie_details.py` · library A–Z/search → `verify_library_jump.py` · startup/tab loading → `repro_runtime.py sections` · scrolling smoothness → release + `repro_runtime.py browse`. Skip suites for untouched areas and say which were skipped.
|
||
|
||
Run only checks relevant to the change. Live playback tests change real Plex progress and can change playback preferences. Restore a useful final state, normally the release build on Home. After a functional debug batch, restore the signed release and its ART profile before returning the device to normal use; never judge performance from an unoptimized debug build.
|
||
|
||
| 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 → Up Next countdown → next episode READY; **debug** |
|
||
| `scripts/repro_runtime.py credits` | Credits → Up Next (mini-player), season/related rows, any-press cancel, Back to video; **debug** |
|
||
| `scripts/device.py screenshot <name>` | Capture to ignored `evidence/private/`; also supports `hierarchy`, `logs`, `launch`, `key` |
|
||
| `scripts/profile_browse.py` | Targeted atrace investigation when navigation performance regresses |
|
||
| `scripts/profile_transitions.py <label>` | Skipped frames per D-pad transition (tabs, hero, rows, Movies) from framestats; first cycle is the first pass after launch; profiled **release**; raw frames kept for `resummarize` |
|
||
| `scripts/trace_transition.py <label> <setup> <keys>` | atrace one transition and list slow UI frames with their nested work |
|
||
| `scripts/profile_home.py <label>` | Hero → Continue Watching frame timing; profiled **release**; `--cold --cycles 1` checks the first transition |
|
||
| `scripts/verify_navigation_sounds.py` | Sound toggle and cold-start persistence; leaves sounds On |
|
||
| `scripts/verify_details.py` | Cast/actor navigation, related shows and watched sync; temporarily marks validated unwatched movie/show fixtures, then restores them |
|
||
| `scripts/verify_details_layout.py` | Fresh TV show header bounds and Seasons before Cast; debug or release |
|
||
| `scripts/verify_movie_details.py` | Movie safe header, related movies and Back focus restoration; debug or release |
|
||
| `scripts/verify_settings.py` | Category navigation, preference-dialog cancellation and live update check; expects Original quality / 80% test preferences |
|
||
| `scripts/verify_library_jump.py` | Scoped Movie/TV categories, A–Z jumps beyond the first page, details/Back focus and exact Silo search |
|
||
| `scripts/verify_player_features.py [phase…]` | Phases `previous_episode`, `auto_skip` (Skipping intro fill, Down/Back cancel), `server_picker` (Back/Cancel), `refresh` (resume and open-app Continue Watching sync; moves and restores Silo 1×1 progress); **debug**; restores skip preferences |
|
||
| `scripts/verify_audio_preferences.py` | Theme persistence and actual playback audio; **debug**; restores prior audio preferences |
|
||
|
||
Live Android integration tests (currently six) cover secure persistence, library APIs, episodes, PIN, preview JPEGs/new seasons and supported HEVC remux negotiation:
|
||
|
||
```powershell
|
||
.\Build.ps1 -Test
|
||
& .tools/gradle-8.13/bin/gradle.bat --no-daemon assembleDebugAndroidTest
|
||
& $KaleidoAdb -s $KaleidoDevice install -r app/build/outputs/apk/debug/app-debug.apk
|
||
& $KaleidoAdb -s $KaleidoDevice install -r app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk
|
||
& $KaleidoAdb -s $KaleidoDevice shell am instrument -w tv.kaleido.app.test/androidx.test.runner.AndroidJUnitRunner
|
||
```
|
||
|
||
These require the private test session. Playback test intents (`testTitleId`, `testOffset`, `testMode`) are **ignored in release builds**. Fixture IDs are server-specific: Silo show `6115`, episodes `7599` → `8594`; movie `9776` is 2 Fast 2 Furious. Revalidate fixtures if the server changes. UI tests also depend on actual hub contents and English labels; diagnose missing fixtures separately from app failures.
|
||
|
||
## Important regression traps
|
||
|
||
- Keep initialization independent of cancellable tab requests and apply section results atomically. Cancelling initialization during a startup tab switch previously left Movies/TV blank.
|
||
- Foreground library sync polls revisions every 15 seconds with a 60-second refresh fallback, and checks within a second of returning to the foreground. The revision includes a Continue Watching fingerprint (membership, order, watch count, progress in 5% steps) so watching on another device shows up without refreshing Home on every poll; pause it for playback/background and stage updates before applying them. Preserve stable hub/card focus IDs and current library filters/range. `LibrarySyncIntegrationTest` tests the real timer against an in-memory HTTP fixture without changing Plex or the encrypted session.
|
||
- Home, Movies and TV stay composed once shown; hidden ones are unplaced, have no semantics and must never request focus (gate effects on `active`). Catalog and rails prefetch through `FramePrefetch`/`CacheWindows`, which must remain a `CacheWindowLogic` or rows stop being kept around. With any accessibility service enabled, Compose walks every composed node after each layout change: keep offscreen rows and cards without semantics (`semanticsOnScreen`). See `docs/runtime-verification.md` (frame pacing).
|
||
- Preserve explicit D-pad row/column targets and fixed card geometry. Avoid expensive beyond-bounds focus searches, per-focus catalog recomposition and full-screen gradient overdraw. Contrast is baked into cached backdrop bitmaps off the main thread.
|
||
- Give every Media3 session a unique ID: next-episode creation can overlap the old controller's disposal. Plex HLS position is absolute; **do not add the requested resume offset again**.
|
||
- Handle remote Back explicitly before default focus handling. Wait for menu focus restoration in tests instead of sending blind rapid button sequences.
|
||
- A text field keeps the D-pad: route Down/IME actions out of Search's field explicitly. Give every `focusRestorer()` a fallback, or it overrides explicit focus targets. Per-card modifiers on browse rows must be `Modifier.Node`s, not `composed {}`, and must not animate per card.
|
||
- Playback has one quality preference (`StreamQuality`): **Original quality** (the default) tries the original file, then Plex HLS, then a 1080p conversion if needed; 4K/1080p/720p/480p ask Plex to convert. A nonempty audio-only track list for a declared video must trigger fallback. Earlier preferences migrate on first read. Debug `testMode` still forces a delivery mode. Augment Plex's existing HEVC target; competing targets previously forced unnecessary conversion. A server copy decision does not prove rendering. Preserve the selected Plex tracks and check actual delivered formats.
|
||
- **ADB screenshots can omit HEVC video on this onn while the actual TV displays it. The user confirmed this.** Do not force transcoding based solely on a blank capture. `scripts/check_video.py` has a pixel assertion that can falsely fail for this reason; use playback logs/rendered-frame evidence and physical TV confirmation as appropriate. Never infer universal HDR/codec support from one test.
|
||
- Preview thumbnails and intro/credit markers depend on server-generated data. Do not fabricate them. Automatic skips (Settings › Playback, 0 = button only) show "Skipping intro/credits" with a filling background rather than a number, count down only while playing, and are cancelled by any remote press (OK on the button skips now; Back only cancels).
|
||
- Theme tracks come from Plex metadata and inherit from the show for seasons/episodes. Stop music on video playback/background. Volume boost was removed because it degraded audio; keep passthrough and the normal audio path.
|
||
- A server-stopped session (Plex dashboard Stop) arrives as `terminationCode`/`terminationText` on the timeline response. Leave the player with the reason and never fall back or reconnect afterwards; timelines keep reporting `buffering` while a stream stalls so the stop is still noticed.
|
||
|
||
### Performance testing
|
||
|
||
Fresh ADB installs may remain in ART `status=verify`, making Compose much slower. Compare matching compilation states. After installing the **release** APK, prepare only Kaleido:
|
||
|
||
```powershell
|
||
& $KaleidoAdb -s $KaleidoDevice shell am broadcast -a androidx.profileinstaller.action.INSTALL_PROFILE -n tv.kaleido.app/androidx.profileinstaller.ProfileInstallReceiver
|
||
& $KaleidoAdb -s $KaleidoDevice shell cmd package compile -f -m speed-profile tv.kaleido.app
|
||
& $KaleidoPython scripts/repro_runtime.py browse
|
||
```
|
||
|
||
The harness requires horizontal Y drift ≤3 px and frame-time p95 <40 ms. On 2026-10-23, the final release measured median 15 ms / p95 27 ms after profile compilation; some frames still missed 60 Hz. This is historical evidence, not a current guarantee. Baseline rules live in `app/src/main/baseline-prof.txt`; ordinary sideloads also depend on Android's background profile optimization.
|
||
|
||
## Releases and further detail
|
||
|
||
Use Semantic Versioning (`major.minor.patch`) for release names.
|
||
|
||
Updates come from `https://git.elijahkuntz.com/Elijah/Kaleido`. Keep the private `.tools/kaleido-signing.jks`; replacing it breaks in-place updates. `version.properties` is the version source. Before a requested release, increment version name/code, update `CHANGELOG.md`, build/test, and use `scripts/package_release.py`; the Forgejo workflow publishes matching version tags. Do not claim publication or updater installation was tested without verifying it.
|
||
|
||
See `docs/design-system.md` for the visual system and `docs/runtime-verification.md` for device evidence and limitations. Keep this file concise; put detailed investigation history there.
|