# TiviLux Native 0.2 — TV UX Mapping

This document records the interaction patterns used as references for the 0.2 living-room redesign. The implementation remains original TiviLux code and branding.

## Live TV / EPG patterns implemented

- Large-screen, remote-control-first navigation.
- Category/group navigation separated from channel/program navigation.
- Traditional horizontal EPG grid with time headers.
- Live preview that can be enabled/disabled.
- Optional autoplay of a highlighted channel in preview.
- Optional stay-on-guide tuning behavior.
- Channel-number and channel-logo controls.
- Provider-order, channel-number, and name sorting.
- Favorites-first option.
- Current-channel highlighting.
- Current-program highlighting and progress.
- Full-height current-time marker.
- Two-line program title mode.
- Guide density and guide font sizing.
- EPG time-offset correction.
- Program synopsis area above the guide.
- Full-screen playback from the guide with Back returning to the guide.

## Why the v0.1 preview appeared hidden

The original Live page reserved fixed widths for the app rail, group list, channel list, gaps and padding before the preview area. On TV devices that expose a relatively narrow Compose dp width, those fixed columns consumed most of the available width and left the preview squeezed into the far-right edge. v0.2 makes the preview a weighted, responsive top panel and gives the EPG the remaining horizontal space.

## Movies

Browse flow: category -> focused poster -> title detail -> Play -> full-screen Media3 player.

The detail screen supports provider-supplied backdrop/poster, title, release date/year, rating, runtime, genre, plot, cast and director, plus My List.

## Series

Browse flow: category -> focused poster -> series detail -> season -> episode -> full-screen Media3 player.

The detail screen supports backdrop/cover, title, year, rating, genre, synopsis, cast, season selector, episode thumbnails, episode number/title, duration, release date and synopsis when the provider returns them.

## Deliberately deferred for a later production pass

These are useful high-end IPTV features but were not added as cosmetic/non-functional toggles in 0.2: catch-up playback, recording/DVR, multiview, parental PIN controls, external-player selection, auto-frame-rate switching, audio passthrough controls, channel-name prefix/suffix editor, persistent resume positions, and full multi-day EPG storage. They should be implemented as real behavior before exposing switches for them.

## v0.2.2 tuned-vs-focused behavior

Live TV now deliberately separates **focused guide item** from **tuned channel**. D-pad navigation is browse-only and never retunes video. OK/Select tunes the channel; the preview keeps that stream while focus continues elsewhere. Hold BACK from the guide for ~650 ms to expand the currently tuned channel full screen. This keeps the familiar TV-guide behavior while avoiding the performance cost and visual disruption of focus-driven channel changes.


## v0.2.3 remote-control mapping

TiviLux now includes the living-room shortcut behavior requested for TV remotes:

- Guide OK: tune channel.
- Guide long OK: Settings.
- Guide long BACK: tuned channel to full screen.
- Guide long LEFT: jump two hours backward in the EPG.
- Full-screen OK: previous channel.
- Full-screen long OK: Quick Menu.
- Full-screen LEFT: channel mini-guide; LEFT again: Groups.
- Full-screen RIGHT: program info at bottom.
- Full-screen long RIGHT: compact program info at upper right.
- Full-screen UP / DOWN: previous/next channel in the loaded Live TV group.
- Full-screen long UP: remove current channel from recent history.
- Full-screen long DOWN: Search.
- Full-screen BACK: return to TV Guide with the tuned channel preserved.

The Settings > Remote Control page documents these defaults and provides a master enable/disable switch. Per-button remapping is still deferred until a dedicated key-binding editor is implemented. Record/Remind is also deferred until it can be backed by a real recording/reminder engine.


## v0.2.4 Sports Hub

Sports is a TiviLux-specific discovery layer over the active Xtream playlist. It does not depend on an external schedule to decide what is playable. The app classifies sports feeds from provider category names, channel titles, major-team channel names and EPG text, then groups duplicate/alternate feeds for the same event. Sports EPG discovery is deliberately deferred until the Sports Hub is entered and is fetched in bounded batches to protect TV responsiveness and provider load.


## v0.3.0 performance note
Full-account XMLTV parsing no longer blocks first entry to Home. The guide primes quickly, visible channels fetch on demand, and the exact provider-wide EPG map finishes in the background and is cached locally.

## v0.3.1 TV navigation / stability pass
- Fullscreen BACK flow is now deterministic: clean video -> HUD -> Guide.
- Fullscreen top-left channel/program bug is part of the HUD lifecycle and hides with the bottom controls.
- Guide restoration tracks the active stream and scrolls directly to it, including streams launched from Sports.
- Header action buttons are responsive and protected from metadata-driven clipping.
- Startup presentation is now a simplified percentage-first experience while catalogs continue to preload in parallel.
