Kaleido/AGENTS.md
Elijah 629546a50c
All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m16s
Smooth section switches and first row moves on weaker TVs
Measured every browse transition on the onn, a Fire TV Stick 4K and a TCL
TV with a new framestats harness and atrace breakdowns.

- Stage card artwork and titles a few cards per frame while a section
  enters, so its first frame no longer composes every card at once.
- Give every discovery list the lookahead cache window and nudge it once
  after a section settles, so the first move down composes nothing.
- Activate a focused top tab two frames later, so its highlight responds
  before the section switches; start the page entrance after composition
  settles, using per-draw alpha instead of an offscreen layer.
- Limit Coil to two concurrent decodes, drop the redundant window
  background, size card image requests explicitly, and skip a coroutine
  per card for focus restoration.

Home -> Movies UI stalls drop from 150-200 ms to 70-90 ms and Movies row
moves no longer skip frames. Device scripts can now target any authorized
serial and tolerate the TCL's flaky network ADB link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 13:11:45 -07:00

95 lines
9.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 two, which add per-frame 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. 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 <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 |
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.
- 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.
- Direct stream is the default preference, with original-file and conversion options available in-player. Augment Plex's existing HEVC target; competing transcode targets previously forced unnecessary H.264 conversion. A server decision to copy video does not itself prove successful rendering.
- **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.
### 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
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.