# TiviLux Native v0.4.18 — Source Audit

## Baseline verified from attached source
- Application ID / namespace: `tv.tivilux.nativeplayer`
- Attached baseline: `versionName 0.4.17`, `versionCode 33`
- New release metadata: `versionName 0.4.18`, `versionCode 34`
- Android: compile/target SDK 35, min SDK 23, Java/Kotlin JVM target 17
- UI: Jetpack Compose
- Playback: AndroidX Media3 / ExoPlayer 1.5.1
- Images: Coil 2.7.0 with app-level memory + disk cache
- Data/provider: Xtream Codes/XUI-style HTTP API plus XMLTV/EPG parsing
- Persistence: encrypted Android Keystore-backed credential blob, SharedPreferences profile/library/settings/progress state, and file-backed segmented startup cache
- Database: no Room/SQLite database layer was found in the current source
- Updater: in-app manifest check/download/install using `latest.json` and same package identity

## Current feature inventory
### Account
- Username/password-only Underground login using a hardcoded provider endpoint in BuildConfig.
- Provider URL is not rendered by LoginScreen.
- Credentials are AES/GCM encrypted with an AndroidKeyStore key before SharedPreferences storage.
- Session supports expiration, active connections, and max connections.

### Profiles
- Local household profiles on one provider account.
- Maximum profile layer and profile-scoped library/progress behavior are implemented in ProfileStore/LibraryStore/PlaybackStore.
- Profile changes do not represent new Xtream accounts.

### Home
- Live TV, Movies, Series, Sports, Favorites, Continue Watching/Next Episode paths, account/profile status, and Settings access.

### Live TV / Guide
- LazyColumn channel virtualization with stable channel IDs.
- Cached EPG map, deferred per-row EPG fetch, groups/categories, favorites, remote handling.
- Persistent preview bounds and shared Live player between Guide and fullscreen.
- Guide remains warm behind Live fullscreen when returning from Live/Favorites.

### Movies / Series
- Provider master catalogs, categories, category filtering, Movie/Series detail, poster art, metadata.
- Suspicious-small-response protection and category-by-category completeness repair are already present.
- Existing larger known-good Movie/Series caches are protected from being overwritten by tiny provider responses.

### VOD progress
- Movie/episode progress, Resume, watched threshold, Continue Watching, Next Episode, optional autoplay-next behavior.
- v0.4.18 adds a per-profile in-memory progress index without changing persistent JSON compatibility.

### Search
- Cross-content Live/Movie/Series search.
- v0.4.18 changes it to debounced background indexed search suitable for large libraries.

### Sports
- NFL, MLB, NBA, NHL structures; normalized channel/team mapping; cached Sports event/summaries; team-feed fallback paths.

### Updates
- Manifest-driven update check, APK download, optional SHA-256 verification, Android package installer, same-package update protection.

## Navigation map
`Login -> Startup -> Home`

From Home/rail:
- `Home -> Live`
- `Home -> Sports`
- `Home -> Movies -> Movie Detail -> VOD Player`
- `Home -> Series -> Series Detail -> Episode/VOD Player`
- `Home -> Favorites -> Favorites Live Guide` when live favorites exist, otherwise Favorites content view
- `Home -> Search -> Detail or Player`
- `Home -> Settings -> Profiles`

Expected VOD back chain remains:
`Player -> Detail -> Movies/Series -> Home -> exit`

Live fullscreen entered from Guide keeps Guide composition warm and returns to the active/anchored Live channel.

## Player lifecycle map
### Live
`rememberTiviLuxPlayer()` creates a shared Live Media3 player at app-composition scope.

`Guide preview -> same external Live player + same PlayerView/surface bounds -> fullscreen resize -> Guide preview resize`

The player is paused when leaving Live/Favorites/Player surfaces but is not recreated for ordinary Guide <-> fullscreen presentation changes.

### VOD
A separate persistent VOD Media3 player is retained at app-composition scope. VOD progress is sampled for UI, persisted periodically, persisted on exit, and marked complete at end/threshold. This remains intentionally separate from Live for stability.

## Existing performance architecture that was preserved
- Segmented startup cache and fast cache metadata.
- Background/staggered refresh after cached startup.
- EPG fetch concurrency gate.
- VOD catalog completeness concurrency gate.
- Lazy Guide rendering and visible-window timeline filtering.
- Guide focus/selection work separated from delayed EPG work.
- Coil memory/disk image cache with crossfade disabled.
- Shared Live player/surface.
- Media3 decoder fallback and bounded data-source timeouts.
- Sports channel indexes and revision-based cached summaries.

## Main expensive operations identified
1. Search repeatedly flattened/de-duplicated/lower-cased very large catalogs on query evaluation.
2. Series episode progress repeatedly reparsed SharedPreferences JSON once per visible episode row.
3. Guide forced a `scrollToItem()` centering operation for every focused-index change.
4. VOD rapid-seek UI could accumulate a number faster than ExoPlayer's `currentPosition` reflected earlier seeks.
5. First/full provider catalog and XMLTV operations are naturally expensive, but the existing project already moves most of those behind cache/background/concurrency controls.

## Regression-sensitive areas deliberately not rewritten
- Xtream request contracts and hidden server flow.
- Update manager / installer flow.
- SmartTune/Turbo Tune stream resolution.
- Sports matching.
- startup cache serialization format.
- Live/VOD player ownership split.
- package/application identity.

## Build audit limitation
The archive contains Gradle build files but no Gradle wrapper (`gradlew`, `gradlew.bat`, `gradle/wrapper/*`). The editing environment also has no Android SDK and no Gradle executable. For that reason a real Android compile could not be executed here. A plain Kotlin compiler syntax-oriented pass was run; it cannot resolve Android/Compose dependencies without their classpath, but it reported zero parser errors matching `expecting`/`unexpected tokens`. The mandatory real build/device checks are listed in `BUILD-CHECKLIST-v0.4.18.txt`.
