Skip to content

StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.

docs: define phase 4 navigation contracts

David Nashashf8ed2719f785
diff --git a/docs/superpowers/specs/2026-08-23-navigation-contracts-design.md b/docs/superpowers/specs/2026-08-23-navigation-contracts-design.md
new file mode 100644
index 00000000..da496633
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-23-navigation-contracts-design.md
@@ -0,0 +1,293 @@
+# Phase 4 Navigation Contracts Design
+
+Date: 2026-08-23
+
+## Status
+
+Proposed design for Phase 4 of the Compose reduction and UI architecture
+plan. This design prepares the application for Phase 5 feature-module
+extraction without changing player composition, playback lifecycle, stream
+recovery, or screen visuals.
+
+## Goal
+
+Separate navigation contracts from Android Navigation implementation and move
+startup/external navigation orchestration out of the root composable, while
+preserving current routes, deep links, player handoffs, return behavior, and
+golden output.
+
+## Current problem
+
+The current navigation package combines several responsibilities:
+
+- `AppNavigation.kt` owns the remembered root `NavHostController`, provider
+ preference collection, landing resolution, startup player lookup, external
+ request consumption, catalog-route correction, and graph composition.
+- `AppNavigationGraph.kt` registers destinations but also performs direct
+ navigation, reads/writes saved-state payloads, resolves player return routes,
+ and owns feature-specific transition behavior.
+- `AppNavigationContracts.kt` contains raw route strings, route builders,
+ domain-object adapters, player request serialization, and Android Navigation
+ imports in one file.
+- `MainActivity` parses platform intents into app navigation requests, while
+ the root composable decides when those requests may be executed.
+- Feature screens receive callbacks today, but the graph implementation still
+ owns the root controller and many feature-specific navigation decisions.
+
+This prevents moving a feature with its graph registration and navigation
+contract into a Phase 5 module without also moving root navigation knowledge.
+
+## Chosen architecture
+
+### `:core:navigation`: contract-only module
+
+Add `:core:navigation` as a small Kotlin/JVM-compatible module with no
+project dependencies and no references to `:app`, `:data`, `:domain`,
+`:player`, Compose, AndroidX Navigation, Hilt, or Activities.
+
+The module owns only stable, serializable navigation values:
+
+- `AppDestination`, a sealed typed destination model for route identity and
+ typed arguments.
+- `PlayerNavigationRequest`, containing primitive player handoff data and a
+ typed optional return destination.
+- `ExternalNavigationRequest`, covering destination, search, player, playlist
+ import, and backup import requests.
+- `NavigationCommand` and `NavigationActions`, the feature-facing navigation
+ contract. These expose navigation intent without exposing `NavController`.
+- Shared navigation keys/contract constants that are required across the app
+ and future feature modules.
+
+The contract model uses primitives, strings, lists of primitives, and other
+core navigation values. Domain objects such as `Channel`, `Movie`, `Episode`,
+`MovieDetailPresentationHint`, and `SeriesDetailPresentationHint` do not cross
+this module boundary. App or future feature modules adapt those objects into
+navigation requests at their ownership boundary.
+
+The contract module does not encode Android route strings. Route syntax,
+argument names, URI encoding, and compatibility parsing remain app adapters
+until a feature module owns its route codec.
+
+### `:app`: platform and composition adapter
+
+The app remains responsible for Android Navigation and app/domain integration:
+
+- `AppRouteCodec` maps `AppDestination` to the existing route strings and
+ decodes supported route arguments.
+- Domain adapters map channels, movies, episodes, and playback history into
+ `PlayerNavigationRequest` values.
+- Legacy external-route parsing maps old route strings into typed
+ `AppDestination` values before navigation execution.
+- Android intent parsing remains at the Activity/platform boundary, including
+ URI validation and the existing backup-file bridge.
+- `NavControllerNavigator` is the only object allowed to translate typed
+ navigation commands into `NavController` operations.
+- App-specific presentation-hint storage remains in the app adapter until the
+ movie and series features move in Phase 5.
+
+The app may depend on `:core:navigation`; the core navigation module may not
+depend on the app or any feature implementation.
+
+## Navigation data flow
+
+```text
+MainActivity / TV launcher / app-owned caller
+ |
+ v
+typed ExternalNavigationRequest or NavigationCommand
+ |
+ v
+AppNavigationCoordinator
+ - startup landing resolution
+ - startup player lookup
+ - external request de-duplication/acknowledgement
+ - lifecycle-safe pending commands
+ |
+ v
+AppNavHost's narrow command collector
+ |
+ v
+NavControllerNavigator
+ |
+ v
+typed AppDestination -> AppRouteCodec -> NavHost route
+```
+
+The root `AppNavigation` composable becomes wiring: it obtains the app
+navigation dependencies, creates/receives the controller, and calls
+`AppNavHost`. It does not resolve startup targets, parse external requests,
+decide catalog corrections, or contain feature navigation branches.
+
+The coordinator owns pending-command state and idempotence. A command is
+acknowledged only after the navigator successfully executes it while the
+current entry is resumed. Recomposition, Activity recreation, and repeated
+`onNewIntent` delivery must not duplicate a startup player launch or external
+request.
+
+## Typed contracts
+
+The exact names may be refined during implementation, but the public shape is
+fixed by these rules:
+
+```kotlin
+sealed interface AppDestination : java.io.Serializable
+
+data class PlayerNavigationRequest(
+ val streamUrl: String,
+ val title: String,
+ val channelId: String? = null,
+ val internalId: Long = -1L,
+ val categoryId: Long? = null,
+ val providerId: Long? = null,
+ val isVirtual: Boolean = false,
+ val combinedProfileId: Long? = null,
+ val combinedSourceFilterProviderId: Long? = null,
+ val contentType: String = "LIVE",
+ val artworkUrl: String? = null,
+ val archiveStartMs: Long? = null,
+ val archiveEndMs: Long? = null,
+ val archiveTitle: String? = null,
+ val returnDestination: AppDestination? = null,
+ val seriesId: Long? = null,
+ val seasonNumber: Int? = null,
+ val episodeNumber: Int? = null,
+ val episodeId: Long? = null
+) : java.io.Serializable
+
+sealed interface ExternalNavigationRequest : java.io.Serializable
+
+sealed interface NavigationCommand : java.io.Serializable
+
+interface NavigationActions {
+ fun navigate(destination: AppDestination)
+ fun openPlayer(request: PlayerNavigationRequest)
+ fun back(): Boolean
+ fun returnTo(destination: AppDestination?): Boolean
+}
+```
+
+`AppDestination` includes typed equivalents for the current top-level,
+detail, provider setup, player, search, guide, settings, plugin, downloads,
+multi-view, and welcome destinations. Optional query values are represented as
+nullable or typed fields rather than embedded route strings. The app route
+codec preserves the existing sentinel/default behavior when converting these
+values to Android Navigation arguments.
+
+Invalid or unsafe player requests remain rejected at the app boundary before
+they reach the player destination. The supported stream-scheme policy is
+unchanged.
+
+## Graph registration and feature isolation
+
+Rename the central graph entry point to `AppNavHost` and keep it primarily a
+registry. It owns the single `NavHost` call, start destination, shared app
+graph dependencies, and registration order. It does not contain feature screen
+branches or startup/external resolution.
+
+Split registration into app-owned extensions that are shaped to move with
+future feature modules:
+
+- `registerWelcomeGraph`
+- `registerProviderGraph`
+- `registerHomeGraph`
+- `registerLiveGraph`
+- `registerCatalogGraph`
+- `registerPlayerGraph`
+- `registerSystemGraph`
+
+Each extension receives typed `NavigationActions` and the minimum feature
+dependencies it needs. No registration extension accepts the root
+`NavHostController`. Destination lambdas may use their own
+`NavBackStackEntry` for typed arguments and saved state, but navigation side
+effects go through `NavigationActions` or a feature-owned app adapter.
+
+This gives Phase 5 a direct extraction unit: a feature module can move its
+screen code, graph registration extension, route argument codec, and feature
+navigation tests together. The app root will retain only registry composition
+and cross-feature navigation policies.
+
+## Startup and external navigation
+
+Extract the current root-composable logic into testable app services:
+
+- `StartupNavigationResolver` resolves the configured landing destination and
+ optional first-favorite/last-watched player request from explicit repository
+ ports and input values. It preserves the current provider/combined-profile,
+ hidden-channel, virtual-category, and return-to-live behavior.
+- `ExternalNavigationRequestParser` converts Activity intents and legacy route
+ extras into typed requests. It preserves search, player, provider setup,
+ playlist import, backup import, and ACTION_VIEW fallback behavior.
+- `AppNavigationCoordinator` accepts startup inputs and external requests,
+ exposes pending typed commands, prevents duplicate handling, and reports
+ acknowledgement only after successful navigation.
+
+`MainActivity` remains responsible for Android-only concerns such as intent
+extras, URI grants, backup inbox copying, and forwarding `onNewIntent`. It no
+longer owns a navigation-specific mutable flow that the root composable must
+interpret directly; it submits typed requests to the coordinator boundary.
+
+## Back and return behavior
+
+Player requests carry a typed optional return destination. The navigator keeps
+the existing preference order:
+
+1. Pop to an existing matching return destination when possible.
+2. Navigate to the typed return destination if it is not already in the stack.
+3. Fall back to Home when no return target exists or the stack cannot be
+ restored.
+
+Movie and series detail presentation hints remain in app-owned saved-state
+adapters during Phase 4. Their behavior and keys remain unchanged. This avoids
+putting domain-specific variant models into `:core:navigation` while preserving
+the handoff needed by the current detail screens.
+
+## Testing strategy
+
+### Core navigation tests
+
+- Every `AppDestination` encodes/identifies its typed arguments without raw
+ route strings.
+- `PlayerNavigationRequest` preserves all fields, including series identity
+ and typed return destination.
+- External request variants are serializable and distinguishable.
+- Navigation action fakes record typed commands without a `NavController`.
+
+### App navigation tests
+
+- Route codec round trips all current destinations and sentinel values.
+- Legacy external routes decode to the same typed destinations as before.
+- Unsafe or missing player URLs are rejected.
+- Startup landing resolution covers normal landing, first favorite, last
+ watched, provider source, combined source, hidden channels, and no-target
+ fallback.
+- External intent parsing covers player, destination, search, playlist import,
+ backup import, malformed legacy route, and ACTION_VIEW fallback.
+- Return-route behavior covers existing-stack pop, missing-stack navigation,
+ and Home fallback.
+
+### Graph and connected coverage
+
+- Registration extensions compile without accepting a root controller.
+- A fake `NavigationActions` verifies screen callbacks emit typed commands.
+- Existing shell, premium-route, player overlay, and player smoke coverage is
+ rerun after the graph split.
+- Connected tests cover startup player requests, external navigation, player
+ return behavior, and deep-link entry on the TV emulator when available.
+
+## Non-goals
+
+- No feature module extraction occurs in Phase 4.
+- No player composition, lifecycle, recovery, or stream policy changes occur.
+- No visual redesign or route renaming occurs.
+- No domain model migration into `:core:navigation` occurs.
+- No claim is made about build-time improvement without before/after
+ measurements.
+
+## Phase 5 handoff
+
+Phase 4 is exit-ready only when `AppNavHost` is a registry, feature graph
+extensions do not receive the root controller, typed contracts are independent
+of app/domain/data/player code, and tests cover deep links, startup player
+requests, return routes, and external navigation. Phase 5 can then move a
+feature by transferring its registration extension and screen-owned adapters
+without expanding the root navigation file.