Skip to content

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

docs(tui): update controls documentation, help screen, and changelog

Samir Hossains1aa0e73ed74d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7840847..d08e8bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,20 @@
## [Unreleased]
### Added
+- **Centralized grapheme-safe text input engine (`TextInputBuffer`)**: unified text
+ editing across TV Playlist and Addon managers with full grapheme-cluster awareness,
+ horizontal cursor navigation (`Left`/`Right`, `Home`/`End`), forward deletion (`Delete`),
+ backward deletion (`Backspace`), word deletion (`Ctrl+W`), whole-line clearing (`Ctrl+U`),
+ and active cursor rendering matching the main search bar.
+- **Harmonized modal & picker navigation**: `Home` (jump to first), `End` (jump to last),
+ `PageUp` (step -5), and `PageDown` (step +5) support across Browse categories, Theme
+ picker, TV Playlist manager, and Addon manager dialogs.
+- **Download confirmation dialog key navigation**: `Tab` and `BackTab` (`Shift+Tab`) support
+ for toggling between `[ Download ]` and `[ Cancel ]` action buttons in addition to
+ `Left`/`Right`.
+- **Standardized status durations & helpers**: semantic tick duration constants
+ (`STATUS_TICKS_SHORT`, `STATUS_TICKS_DEFAULT`, `STATUS_TICKS_LONG`) and ergonomic
+ `AppState` status helper methods replacing magic number literals across all TUI subsystems.
- **Terminal-aware rendering overhaul**:
- Theme autodetection now actually runs when no explicit theme is configured:
`NO_COLOR` forces monochrome, truecolor terminals get full RGB palettes,
diff --git a/docs/controls.md b/docs/controls.md
index 5f65e8e..1e53e75 100644
--- a/docs/controls.md
+++ b/docs/controls.md
@@ -6,18 +6,52 @@ MovieBox-TUI is designed for fast keyboard navigation with complete mouse suppor
| Key | Action |
| :--- | :--- |
-| **Arrow keys** | Navigate lists, search results, tabs, and modal dialogs |
+| **Arrow keys** | Navigate lists, search results, tabs, and move cursor in input fields |
+| **`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 |
-| **`Tab`** | Auto-complete active search suggestion / slash command in input mode |
-| **`Ctrl+U`** | Clear entire search input line in input mode |
-| **`Ctrl+W`** | Delete backward word in search input |
+| **`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 |
+| **`Ctrl+U`** | Clear entire input line (Search, TV URL, Addon URL) |
+| **`Ctrl+W`** | Delete backward word in text inputs |
| **`Ctrl+S`** | Switch to standard **Streaming Mode** |
| **`Ctrl+T`** | Toggle / switch to **TV Mode** |
| **`Ctrl+A`** | Toggle / switch to **Addon Mode** |
| **`?`** | Open interactive in-app help menu |
| **`Ctrl+C` / `q`** | Quit application and restore terminal |
+## Text Input & Cursor Editing
+
+Text editing across Search, TV Playlist Manager, and Addon Manager uses a unified grapheme-safe input engine:
+
+| Key | Action |
+| :--- | :--- |
+| **`Left` / `Right`** | Move text cursor one grapheme cluster left or right |
+| **`Home` / `End`** | Jump cursor directly to the beginning or end of the input line |
+| **`Backspace`** | Delete the grapheme cluster immediately before the cursor |
+| **`Delete`** | Delete the grapheme cluster at the cursor position |
+| **`Ctrl+W`** | Delete the preceding word (up to space or punctuation delimiter) |
+| **`Ctrl+U`** | Clear the entire input buffer |
+| **`Tab`** | Auto-complete active search suggestion or slash command |
+| **`Enter`** | Submit search query, save TV playlist URL/path, or verify and install Addon manifest |
+| **`Esc`** | Cancel input, dismiss input prompt, or clear search buffer |
+
+## Modal Dialogs & Pickers
+
+All popup dialogs (Theme picker, Browse categories, Player picker, TV Manager, Addon Manager, Download Confirmation) support standard keyboard controls:
+
+- **`↑` / `↓`**: Move selection up / down by one item.
+- **`Home` / `End`**: Jump immediately to the first or last item in the list.
+- **`PageUp` / `PageDown`**: Step up or down by 5 items.
+- **`Enter`**: Confirm selection, activate entry, or submit dialog.
+- **`Esc`**: Dismiss popup dialog without applying changes.
+- **Download Confirmation Dialog**:
+ - **`Tab` / `Shift+Tab` / `BackTab`**: Toggle active selection between `[ Download ]` and `[ Cancel ]`.
+ - **`Left` / `Right`**: Switch between `[ Download ]` and `[ Cancel ]`.
+ - **`Enter`**: Confirm the currently focused action.
+ - **`Esc`**: Cancel and close the confirmation dialog.
## Mode-Specific Controls
### Streaming Mode
diff --git a/docs/known-issues.md b/docs/known-issues.md
index 44691c0..efc3f33 100644
--- a/docs/known-issues.md
+++ b/docs/known-issues.md
@@ -29,6 +29,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 207 unit and integration tests across 16 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 214 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.
- 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/src/tui/screens/help.rs b/src/tui/screens/help.rs
index 4697060..1ffeee4 100644
--- a/src/tui/screens/help.rs
+++ b/src/tui/screens/help.rs
@@ -52,15 +52,23 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState, theme: &Theme) {
]),
Line::from(vec![
Span::styled(" [←] / [→] ", theme.header),
- Span::styled("Jump Page of Results", theme.text),
+ Span::styled("Jump Page / Move Input Cursor", theme.text),
+ ]),
+ Line::from(vec![
+ Span::styled(" [Home] / [End] ", theme.header),
+ Span::styled("Jump Start / End of List or Line", theme.text),
+ ]),
+ Line::from(vec![
+ Span::styled(" [PgUp] / [PgDn]", theme.header),
+ Span::styled("Page Up / Down in Lists", theme.text),
]),
Line::from(vec![
Span::styled(" [Tab] ", theme.header),
- Span::styled("Auto-complete Suggestion / Command", theme.text),
+ Span::styled("Auto-complete / Toggle Dialog Button", theme.text),
]),
Line::from(vec![
Span::styled(" [Ctrl+U] ", theme.header),
- Span::styled("Clear Search Input Line", theme.text),
+ Span::styled("Clear Search / Input Line", theme.text),
]),
Line::from(vec![
Span::styled(" [Ctrl+W] ", theme.header),
@@ -68,7 +76,7 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState, theme: &Theme) {
]),
Line::from(vec![
Span::styled(" [Esc] ", theme.header),
- Span::styled("Go Back / Clear Input", theme.text),
+ Span::styled("Go Back / Clear Input / Dismiss", theme.text),
]),
Line::from(vec![
Span::styled(" [?] ", theme.header),