Skip to content

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

docs(tui): update documentation, changelog, and help modal with latest UX features

Samir Hossains892651e442c6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a214b11..56fae89 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,25 @@
## [Unreleased]
### Added
+- **Preferred subtitle auto-selection**: Added `preferred_subtitle_language` (default `"English"`)
+ and `auto_load_subtitles` (default `true`) configuration options. When playback resolves,
+ matching subtitle tracks are automatically attached and the player launches immediately,
+ bypassing the repetitive subtitle picker popup during binge-watching.
+- **1-Key direct watch history resume (`Space` / `P`)**: Pressing `Space` or `P` on any item in
+ `/history` immediately launches direct playback for the recorded season and episode without
+ manual Details navigation. Opening Details from history (`Enter`) pre-seeds selection to the
+ recorded season/episode.
+- **Non-destructive `Esc` search navigation & `/clear`**: In `Normal` mode with active search results,
+ pressing `Esc` focuses the search bar (`InputMode::Editing`) for quick query adjustments rather
+ than wiping results; pressing `Esc` on an empty query or using `/clear` returns to landing cleanly.
+- **Actionable zero-results & multi-line wrapped error cards**: Zero-results states now display
+ interactive guidance shortcuts (`[Ctrl+P] Switch provider`, `[/browse] Browse categories`,
+ `[Ctrl+U] Clear`), and error states wrap full diagnostic descriptions with `[r] Retry request`
+ and `[Esc] Back` action pills.
+- **Synopsis wrap line-clamping & Details fetch error fallback**: Synopsis paragraphs are now bounded
+ by actual visual line capacity with `wrap_text` rather than raw character counts, and failed
+ details fetches render an actionable error box (`[r] Retry fetch`, `[Esc] Back`) rather than
+ hanging indefinitely on the loading spinner.
- **Grapheme-safe search & text input centralization (`TextInputBuffer`)**: Unified all text
editing across the main Search Bar, TV Playlist Manager, and Addon Manager with full
grapheme-cluster awareness, horizontal cursor navigation (`Left`/`Right`, `Home`/`End`),
diff --git a/docs/config.md b/docs/config.md
index 048d618..550fad8 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -17,6 +17,8 @@ macOS `~/Library/Application Support/moviebox-tui`, Linux `~/.config/moviebox-tu
| `tv_enabled` | bool | Enable TV Mode navigation in bottom dock (`/enable-tv`, `/disable-tv`). |
| `addons_enabled` | bool | Enable Addon Mode navigation in bottom dock (`/enable-addons`, `/disable-addons`). |
| `default_player` | string or null | Preferred player: `mpv`, `iina`, `vlc`, `android`; absent/null until you choose one from the in-app picker. |
+| `preferred_subtitle_language` | string or null | Preferred subtitle language for auto-selection (default `"English"`; case-insensitive matching). |
+| `auto_load_subtitles` | bool | Automatically load and attach matching preferred subtitles without opening the picker modal (default `true`). |
| `download_dir` | string or null | Custom directory for video and subtitle downloads (null uses OS default). |
## Other persisted files
diff --git a/docs/controls.md b/docs/controls.md
index 08906ee..338b677 100644
--- a/docs/controls.md
+++ b/docs/controls.md
@@ -11,7 +11,8 @@ MovieBox-TUI is designed for fast keyboard navigation with complete mouse suppor
| **`Home` / `End`** | Jump to start / end of list, results grid, or text input line |
| **`PageUp` / `PageDown`** | Scroll lists and modal pickers by 5 items (or scroll help overlay) |
| **`Enter`** | Open, play, or confirm the selected item |
-| **`Esc`** | Go back, dismiss popup dialog, or clear active search |
+| **`Space` / `P`** | Direct resume playback for recorded season/episode on `/history` items |
+| **`Esc`** | Focus search input (when results present), dismiss popup dialog, or return to landing |
| **`Tab` / `Shift+Tab`** | Auto-complete suggestion / command; switch details panes; toggle dialog buttons |
| **`Backspace`** | Delete character before cursor, or return focus to search bar from results |
| **`Delete`** | Delete character at cursor in text inputs, or remove entry in TV/Addon managers |
@@ -65,8 +66,9 @@ All popup dialogs (Theme picker, Browse categories, Player picker, TV Manager, A
- **`*` / `f`**: Favorite / unfavorite the selected title on the Home screen.
- **`f`**: Favorite / unfavorite the open title on the Details screen.
- **`/browse`**: Open curated browse categories (Trending, Popular, Top Rated, etc.).
-- **`/history`**: Open watch history.
+- **`/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.
### TV Mode (Live IPTV)
- **`Enter`**: Play selected TV channel immediately.
- **`o`**: Open player selection picker for the channel.
@@ -83,8 +85,9 @@ All popup dialogs (Theme picker, Browse categories, Player picker, TV Manager, A
- **`r`**: Refresh addon catalog search results.
- **`*` / `f`**: Favorite / unfavorite the selected title on the Home screen.
- **`f`**: Favorite / unfavorite the open title on the Details screen.
-- **`/browse`**: Browse curated addon catalogs (Top Movies, Top Series, Top Rated).
+- **`/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.
## Mouse Controls
| Action | Result |
diff --git a/src/tui/screens/help.rs b/src/tui/screens/help.rs
index 946116d..c374997 100644
--- a/src/tui/screens/help.rs
+++ b/src/tui/screens/help.rs
@@ -205,7 +205,7 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState, theme: &Theme) {
]));
help_text.push(Line::from(vec![
Span::styled(" /history ", theme.header),
- Span::styled("Watch History", theme.text),
+ Span::styled("Watch History ([Space] Direct Resume)", theme.text),
]));
help_text.push(Line::from(vec![
Span::styled(" /favorites ", theme.header),