Skip to content

Terminal interface to find, download, and stream movies, TV shows, and live TV using local media players.

docs: update documentation, testing metrics, and readme for responsive layout and 4khdhub stream engine

Samir Hossains295b1677ce08
diff --git a/README.md b/README.md
index d2121e6..2e0bbf1 100644
--- a/README.md
+++ b/README.md
@@ -34,12 +34,12 @@ Searching and watching media through web browsers often means dealing with heavy
## Features at a Glance
- **Search Everything:** Find movies, TV shows, anime, and live TV channels across multiple sources (MovieBox, 4KHDHub, BDIX mirrors, community HTTP addons, and custom IPTV playlists). Features dynamic rotating search suggestions, precision vertical beam cursor with typing debounce, grapheme-safe input, and autocomplete discovery.
-- **Stream Details & Media Badges:** High-contrast color-coded resolution badges (4K UHD, 1080p FHD, 720p HD, SD) and audio/codec tags (`HDR`, `DV`, `ATMOS`, `5.1`, `HEVC`, `AV1`, `BluRay`, `WEB-DL`, `REMUX`) with smooth horizontal pane navigation (`←`/`→`/`h`/`l`/`Tab`).
+- **Stream Details & Media Badges:** Responsive multi-tier details layout with adaptive selector panes (Audio, Seasons, Episodes), color-coded resolution badges (4K UHD, 1080p FHD, 720p HD, SD), and audio/codec tags (`HDR`, `DV`, `ATMOS`, `5.1`, `HEVC`, `AV1`, `BluRay`, `WEB-DL`, `REMUX`) with smooth horizontal pane navigation (`←`/`→`/`h`/`l`/`Tab`).
- **Addon Mode:** Install community HTTP addon manifests for custom catalog metadata (Cinemeta, Anime Kitsu) and direct stream resolution.
- **Smooth Video Playback:** Plays directly in **mpv** or **VLC**, with **IINA** available on macOS, using your computer's hardware for smooth video.
- **Easy Downloads:** Download single episodes or entire seasons with one keypress. Completed episodes are skipped automatically.
- **Favorites:** Star any movie or series with `*` (or `f` on the details screen) and reach it instantly from a dedicated row on the home screen, or view the full list with `/favorites`.
-- **Refined Terminal Interface:** Full keyboard and mouse support, responsive multi-column grid, fluid 10-frame Braille loading spinners, WCAG AA contrast light/dark themes (Catppuccin Latte/Mocha, Nord, TokyoNight, Dracula, Gruvbox, Rosé Pine), contextual window titles, and modal-gated poster art.
+- **Refined Terminal Interface:** Full keyboard and mouse support, responsive multi-column grid, compact single-column narrow terminal fallbacks, fluid 10-frame Braille loading spinners, WCAG AA contrast light/dark themes (Catppuccin Latte/Mocha, Nord, TokyoNight, Dracula, Gruvbox, Rosé Pine), contextual window titles, and modal-gated poster art.
## Installation
A media player (**[mpv](https://mpv.io)** or **[VLC](https://www.videolan.org/vlc/)**; **[IINA](https://iina.io)** on macOS) is recommended for video playback.
diff --git a/docs/controls.md b/docs/controls.md
index eb81149..88f905a 100644
--- a/docs/controls.md
+++ b/docs/controls.md
@@ -72,12 +72,13 @@ All popup dialogs (Theme picker, Browse categories, Player picker, TV Manager, A
- **`/history`**: Open watch history (`Space` or `P` to instantly resume recorded episode/movie).
- **`/favorites`**: Open your starred titles.
- **`/clear`**: Clear active search query and return to landing.
+
+### Live TV Mode
- **`Enter`**: Play selected TV channel immediately.
- **`o`**: Open player selection picker for the channel.
- **`r`**: Reload all active M3U playlist sources.
- **`/config`**: Open TV Playlist Manager dialog (`Space` to activate, `Delete`/`d` to remove).
- **`/list`**: Show all loaded channels.
-
### Addon Mode (HTTP Addons)
- **`Ctrl+P` / `/config`**: Open Addon Manager dialog (`Space` to toggle, `Delete`/`d` to remove).
- **`←` / `→` / `h` / `l` / `Tab` / `Shift+Tab`**: Switch Details screen selector panes (Seasons, Episodes, Streams).
diff --git a/docs/known-issues.md b/docs/known-issues.md
index 163d893..2a440d7 100644
--- a/docs/known-issues.md
+++ b/docs/known-issues.md
@@ -18,9 +18,7 @@ Tracked here so future work and issue reports reference the same facts.
## Environment-dependent
-- **4KHDHub mirrors rotate and can be region/rate limited.** A file whose only mirrors
- are "probe trap" workers (which refuse real streaming ranges) reports
- `no playable mirrors` with the reason in the log. Not fixable in-app.
+- **4KHDHub mirrors rotate and can be expired on upstream hosts.** Direct streams are resolved concurrently across all available release mirrors using prioritized scoring (Fast Direct Google/CDN $\to$ PixelDrain $\to$ Storage $\to$ Workers) and bounded concurrency (`select_ok` in chunks of 3). When all upstream mirrors for an older release are dead/expired (e.g. 404 or expired tokens), the resolver fails fast (<4.5s) and guides the user to select another release.
- **Termux playback needs the device confirmed** on each release: `termux-open` /
`am` availability and the Android chooser behavior. The historical
`rustls-platform-verifier` initialization panic reported for v0.1.12 is not in
@@ -29,6 +27,6 @@ Tracked here so future work and issue reports reference the same facts.
## Verification
-- Automated testing is enforced via `cargo test --all-features --locked` covering 296+ unit and integration tests across 19 test suites (see [`docs/testing.md`](testing.md)). The count is updated when tests change; it does not replace real-player and real-device verification.
+- Automated testing is enforced via `cargo test --all-features --locked` covering 310+ unit and integration tests across 21 test suites (see [`docs/testing.md`](testing.md)). The count is updated when tests change; it does not replace real-player and real-device verification.
- Static correctness is enforced by strict compiler type checking, the lint gate (`cargo clippy --all-targets --all-features --locked -- -D warnings`), formatting (`cargo fmt --check`), dependency vulnerability scanning (`cargo audit`), and packaging verification (`cargo package --locked`).
- Runtime and platform-specific behavior (terminal resize, focus handling, external player launch, and Termux chooser) are verified through the release checklist in [`release-checklist.md`](release-checklist.md).
diff --git a/docs/testing.md b/docs/testing.md
index 459e26b..9f42f7f 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -4,8 +4,7 @@ This document describes the testing architecture, quality assurance procedures,
## 1. Test Architecture
-The test suite comprises **296+ automated tests across 19 test suites** (158 unit tests in `src/lib.rs`, 0 binary tests in `src/main.rs`, and 138 integration tests across 18 test suites in `tests/`), running fully offline by default without mocking or live network dependencies.
-
+The test suite comprises **310+ automated tests across 21 test suites** (170 unit tests in `src/lib.rs`, 0 binary tests in `src/main.rs`, and 140 integration tests across 20 test suites in `tests/`), running fully offline by default without mocking or live network dependencies.
The MovieBox-TUI test architecture follows a strict separation of concerns:
```text
@@ -64,7 +63,7 @@ Integration tests live in the `tests/` directory and test externally observable
- **`m3u_integration.rs`**: Validates parsing of standard, single-quoted, double-quoted, and unquoted M3U playlists using fixtures.
- **`addons_manifest.rs`**: Validates deserialization of Cinemeta/Stremio addon manifests, series vs movie metadata classification, multi-season episode decomposition, episode stream isolation (`parse_season_episode`), token and codec parsing, and movie stream regressions.
- **`url_security.rs`**: Validates HTTP/HTTPS URL detection and Windows reserved device stem sanitization (`CON`, `AUX`, `PRN`, `NUL`, `COM1-9`, `LPT1-9`).
-- **`live_stream_verification.rs`**: Validates real-world MovieBox CDN stream link resolution for movies and TV series, verifying that the backend returns valid signed MP4 streams and that legacy upgrade notice hashes (`1c7de0bd...`) are rejected. The tests are `#[ignore]`-gated for offline execution; opt in with `cargo test --test live_stream_verification -- --ignored`.
+- **`live_stream_verification.rs`**: Validates real-world stream link resolution across MovieBox signed CDN endpoints and 4KHDHub multi-mirror releases (verifying fast <3.5s direct stream resolution on working mirrors and fast <4.5s failure with actionable diagnostics on expired torrents). The tests are `#[ignore]`-gated for offline execution; opt in with `cargo test --test live_stream_verification -- --ignored`.
---