Skip to content

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

fix(tui): eliminate poster placeholder overlap and results background bleed-through

Samir Hossains05821ce9c057
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d08e8bf..a214b11 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,11 +3,40 @@
## [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.
+- **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`),
+ forward deletion (`Delete`), backward deletion (`Backspace`), backward word deletion (`Ctrl+W`),
+ and whole-line clearing (`Ctrl+U`).
+- **High-contrast media resolution badges & audio/codec tags**: Color-coded, high-contrast
+ media resolution badges (`4K UHD`, `1080p FHD`, `720p HD`, `SD`) and granular audio/video
+ codec tags (`HDR`, `DV`, `ATMOS`, `5.1`, `HEVC`, `AV1`, `BluRay`, `WEB-DL`, `REMUX`) in Details
+ stream listings, with theme-aware foreground/background contrast styling and clean bracketed
+ ASCII fallbacks on basic terminals.
+- **Smooth 10-frame Unicode Braille loading spinners**: Added fluid 10-frame Braille animation
+ spinners (`⠋`, `⠙`, `⠹`, `⠸`, `⠼`, `⠴`, `⠦`, `⠧`, `⠇`, `⠏`) for search queries, metadata discovery,
+ and stream fetching states, with graceful 2-character ASCII fallback (`..`) on basic terminals.
+- **Horizontal Details pane navigation (`Left`/`Right`/`h`/`l`)**: Added intuitive horizontal
+ directional navigation (`Left`/`Right` and `h`/`l` vim keys) to smoothly cycle between Audio
+ Languages, Seasons, Episodes, and Streams panes in the Details view alongside `Tab` and `Shift+Tab`.
+- **Surfaced backdrop container for slash command suggestions**: Autocomplete and slash command
+ suggestions now render inside a dedicated `theme.surface0` background container with clear
+ tree-branch hierarchy glyphs (`├─`, `└─` with `|-`, `\-` fallbacks) and aligned descriptions.
+- **Toast notification clearance & visual countdown progress bar**: Elevated toast notifications
+ dynamically adjust their bottom clearance (`bottom_offset: 5`) when the active download gauge
+ is visible to prevent visual collisions, and feature a live countdown progress bar (`━───` and
+ `[==--]`) indicating remaining toast lifespan.
+- **Contextual terminal window titles**: Dynamically updates the terminal emulator window title
+ based on active navigation state (`MovieBox-Tui — Streaming`, `MovieBox-Tui — Live TV`,
+ `MovieBox-Tui — Addons`, and `MovieBox-Tui — {Title}` on Details screens).
+- **Modal graphic anti-bleed gating (`has_active_modal()`)**: Suppresses background Kitty, Sixel,
+ and iTerm2 poster rendering whenever any modal overlay or dialog is active (Help, Theme picker,
+ Browse categories, TV/Addon managers, Subtitles, Player picker, and Download confirmation),
+ preventing terminal graphics from bleeding through popup borders and text.
+- **Catppuccin Latte light theme & Basic 16-color ANSI light palette**: Tuned Catppuccin Latte
+ colors to meet WCAG AA contrast standards on light terminal backgrounds, and introduced a
+ specialized 16-color ANSI light fallback palette (`Theme::fallback(true)`) ensuring crisp
+ readability without truecolor support.
- **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.
@@ -65,6 +94,13 @@
`/toggle-bdix`, `/toggle-streaming`) with backward-compatible aliases.
### Fixed
+- **Poster placeholder overlap on loaded images**: Fixed a rendering bug on the Home
+ results screen where the fallback placeholder widget was unconditionally drawn on top
+ of loaded poster image protocols; the placeholder is now restricted to the `else` branch
+ when an image is still fetching or unavailable.
+- **Results view background bleed-through**: Added explicit area clearing for the results
+ chunk before rendering search cards, eliminating ghost text artifacts (such as ASCII
+ headers or landing row labels) bleeding through beneath unselected cards in multi-column grids.
- **Modal key trapping & isolation**: structural modal gating prevents mode
chords (`Ctrl+T`, `Ctrl+A`, `Ctrl+S`, `Ctrl+P`), download cancellation (`x`),
and background pane navigation from leaking into open dialogs and inputs.
diff --git a/README.md b/README.md
index b48e0a1..f9a06c2 100644
--- a/README.md
+++ b/README.md
@@ -33,13 +33,13 @@ 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).
+- **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). Grapheme-safe search input with word deletion, line clearing, and autocomplete suggestions.
+- **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`).
- **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`.
-- **Simple Terminal Interface:** Full keyboard and mouse support, beautiful color themes, and movie poster art.
-
+- **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.
## 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/addons-mode.md b/docs/addons-mode.md
index 9c3a70b..8b588ee 100644
--- a/docs/addons-mode.md
+++ b/docs/addons-mode.md
@@ -8,8 +8,8 @@ Addon Mode enables support for community HTTP addon manifests. You can install a
- **Core Metadata Protection**: Cinemeta is pre-installed out-of-the-box as the core metadata provider (`[Core]`) and locked to prevent accidental removal.
- **Direct HTTP Stream Engine**: Automatically extracts and filters direct Cloudflare R2, PixelDrain, direct video CDN, and HubCloud/HubDrive HTTP streams.
- **Multi-Addon Concurrency**: Simultaneously queries all enabled stream addons and aggregates releases.
-- **Quality & Size Parsing**: Ranks streams by quality (`4K UHD / 2160p`, `1080p`, `720p`, `SD`), file size in GB/MB, and audio language tracks (e.g. `[Dual]`, `[Multi]`, `Hindi + English`).
-- **Series & Episode Hierarchy**: Series are automatically organized into explicit `Seasons` and `Episodes` selector panes. Selecting any episode drives episode-specific stream requests (`/stream/series/:id:season:episode.json`).
+- **Quality, Resolution & Codec Parsing**: Ranks streams with high-contrast color-coded resolution badges (`4K UHD`, `1080p FHD`, `720p HD`, `SD`) and granular audio/video codec tags (`HDR`, `DV`, `ATMOS`, `5.1`, `HEVC`, `AV1`, `BluRay`, `WEB-DL`, `REMUX`), file size in GB/MB, and audio language tracks (e.g. `[Dual]`, `[Multi]`, `Hindi + English`).
+- **Series & Episode Hierarchy**: Series are automatically organized into explicit `Seasons` and `Episodes` selector panes with smooth horizontal navigation (`←`/`→`/`h`/`l`/`Tab`). Selecting any episode drives episode-specific stream requests (`/stream/series/:id:season:episode.json`).
- **Episode Stream Isolation**: Built-in token parsing (`parse_season_episode`) guarantees that only streams matching the selected season and episode are displayed, eliminating cross-episode stream mixing.
- **Direct Playback & Custom Headers**: Video stream headers (`behaviorHints.headers`) such as `Referer` and `User-Agent` are preserved and forwarded directly to external media players (`mpv`, `IINA`, `VLC`) and the multi-segment downloader.
- **Watch History & Progress Parity**: Full `/history` support in Addon Mode with real-time `mpv` position tracking, scrub lines, and auto-resume.
diff --git a/docs/config.md b/docs/config.md
index 5fb3ee1..048d618 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -39,7 +39,7 @@ macOS `~/Library/Application Support/moviebox-tui`, Linux `~/.config/moviebox-tu
| `MOVIEBOX_VLC_PATH` | Custom VLC executable. |
| `MOVIEBOX_IINA_PATH` | Custom IINA/iina-cli executable. |
| `MOVIEBOX_FOURKHDHUB_URL` | Override the 4KHDHub base URL. |
-| `MOVIEBOX_THEME` | Force a theme (e.g. `Dracula`, `Gruvbox`, `Nord`, `Mocha`, `RosePine`, etc.). When unset and no saved theme exists, the app auto-detects: `NO_COLOR` wins, truecolor terminals get full palettes, 256-color terminals get quantized palettes, and the OSC 11 background query picks light/dark variants. |
+| `MOVIEBOX_THEME` | Force a theme (e.g. `Mocha`, `Latte`, `Macchiato`, `Frappe`, `Nord`, `TokyoNight`, `Dracula`, `Gruvbox`, `RosePine`). When unset and no saved theme exists, the app auto-detects: `NO_COLOR` wins, truecolor terminals get full palettes, 256-color terminals get quantized palettes, and the OSC 11 background query picks light/dark variants with WCAG AA contrast. |
| `MOVIEBOX_NO_IMAGE` | Disable poster image queries (set to `1` or `true`). |
| `MOVIEBOX_IMAGE_PROTOCOL` | Force poster graphics protocol: `kitty`, `sixel`, `iterm2`, or `none`. |
| `MOVIEBOX_CELL_SIZE` | Override terminal cell size as `WxH` (e.g. `10x20`) for poster scaling. |
diff --git a/docs/controls.md b/docs/controls.md
index 1e53e75..08906ee 100644
--- a/docs/controls.md
+++ b/docs/controls.md
@@ -6,11 +6,12 @@ MovieBox-TUI is designed for fast keyboard navigation with complete mouse suppor
| Key | Action |
| :--- | :--- |
-| **Arrow keys** | Navigate lists, search results, tabs, and move cursor in input fields |
+| **`↑` / `↓` / `k` / `j`** | Navigate lists, search results, or move cursor up/down |
+| **`←` / `→` / `h` / `l`** | Move text input cursor, step wide grid columns, or switch Details panes (Audio/Seasons/Episodes/Streams) |
| **`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 |
+| **`Enter`** | Open, play, or confirm the selected item |
+| **`Esc`** | Go back, dismiss popup dialog, or clear active search |
| **`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 |
@@ -56,7 +57,7 @@ All popup dialogs (Theme picker, Browse categories, Player picker, TV Manager, A
### Streaming Mode
- **`Ctrl+P`**: Cycle content providers (`MovieBox` $\to$ `4KHDHub` $\to$ `BDIX`).
-- **`Tab` / `Shift+Tab`**: Switch details screen panes (Seasons, Episodes, Streams, Overview).
+- **`←` / `→` / `h` / `l` / `Tab` / `Shift+Tab`**: Switch Details screen selector panes (Audio Languages, Seasons, Episodes, Streams).
- **`Enter`**: Play with default player.
- **`o`**: Open player selection picker for the current stream.
- **`d`**: Download current episode or full season batch.
@@ -66,7 +67,6 @@ All popup dialogs (Theme picker, Browse categories, Player picker, TV Manager, A
- **`/browse`**: Open curated browse categories (Trending, Popular, Top Rated, etc.).
- **`/history`**: Open watch history.
- **`/favorites`**: Open your starred titles.
-
### TV Mode (Live IPTV)
- **`Enter`**: Play selected TV channel immediately.
- **`o`**: Open player selection picker for the channel.
@@ -76,6 +76,7 @@ All popup dialogs (Theme picker, Browse categories, Player picker, TV Manager, A
### 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).
- **`Enter`**: Select title or play resolved stream.
- **`o`**: Open player selection picker for the stream.
- **`d`**: Download HTTP stream release.
@@ -84,7 +85,6 @@ All popup dialogs (Theme picker, Browse categories, Player picker, TV Manager, A
- **`f`**: Favorite / unfavorite the open title on the Details screen.
- **`/browse`**: Browse curated addon catalogs (Top Movies, Top Series, Top Rated).
- **`/favorites`**: Open your starred titles.
-
## Mouse Controls
| Action | Result |
diff --git a/docs/cross-platform.md b/docs/cross-platform.md
index 5d3b77d..03f7487 100644
--- a/docs/cross-platform.md
+++ b/docs/cross-platform.md
@@ -27,20 +27,30 @@ nothing, and on demand via `/probe`):
detects them. Terminals that report kitty/sixel capability but no cell
size (Windows Terminal sixel, iTerm2 over SSH) are salvaged with default
cell metrics. True Halfblocks-only terminals show a compact filmstrip
- placeholder instead. `MOVIEBOX_NO_IMAGE=1` disables queries;
+ placeholder instead. All poster image rendering is automatically gated
+ behind `has_active_modal()` to prevent image protocol graphic bleed
+ through modal popups and overlays. `MOVIEBOX_NO_IMAGE=1` disables queries;
`MOVIEBOX_IMAGE_PROTOCOL` forces a protocol; `MOVIEBOX_CELL_SIZE=WxH`
overrides metrics.
-- **Colors**: With no explicit theme, `NO_COLOR` wins, then truecolor RGB,
- quantized 256-color palettes for strict terminals, ANSI fallback
- otherwise; an OSC 11 background query picks light/dark variants. An
- explicit `MOVIEBOX_THEME` or saved theme always wins over autodetection.
-- **Keyboard**: The kitty keyboard protocol (disambiguated escapes, event
+- **Colors & Themes**: With no explicit theme, `NO_COLOR` wins, then truecolor RGB,
+ quantized 256-color palettes for strict terminals, and a 16-color ANSI fallback
+ palette (`Theme::fallback`); an OSC 11 background query picks light/dark variants.
+ Light mode themes (including Catppuccin Latte) are tuned for WCAG AA compliance,
+ ensuring high-contrast readability across light terminal backgrounds. An explicit
+ `MOVIEBOX_THEME` or saved theme always wins over autodetection.
+- **Keyboard & Cursor**: The kitty keyboard protocol (disambiguated escapes, event
types) is requested at start and popped on exit; unsupported terminals
- ignore it.
+ ignore it. Real input cursor styling (`SetCursorStyle::SteadyBar`) activates
+ during text editing modes on supported terminals.
+- **Loading & Progress Animations**: Fluid 10-frame Unicode Braille loading
+ spinners (`⠋ ⠙ ⠹ ...`) render during search, metadata discovery, and stream
+ fetching, falling back to clean text indicators (`..`) on basic/dumb terminals.
+- **Window Titles**: Contextual terminal emulator window titles are emitted dynamically
+ reflecting active navigation mode and title (`MovieBox-Tui — Streaming`,
+ `MovieBox-Tui — Live TV`, `MovieBox-Tui — Addons`, `MovieBox-Tui — {Title}`).
- **Terminal classification**: `TERM=dumb`/`linux` fall back to a basic UI.
- Focus events re-render in place without clearing; results render in two
columns from 110 columns wide (three from 160).
-
## Network & TLS portability
- **TLS Engine**: Uses `rustls` with embedded Mozilla roots (`webpki-roots`) across all targets (macOS, Linux, Windows, Android/Termux). The release binary has no OpenSSL runtime dependency; the `ring` cryptography backend is compiled into the binary by the platform build toolchain.
diff --git a/docs/modules.md b/docs/modules.md
index 939584a..bf50097 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -97,7 +97,7 @@ src/
help.rs Keybinding help (mode-aware).
terminal.rs Terminal capability probes (basic UI, image querying).
theme.rs Color themes + terminal color detection.
- text.rs Grapheme-safe width/truncation helpers.
+ text.rs Grapheme-safe text input buffer (TextInputBuffer) and width/truncation helpers.
tui/app/ The application object (App) and all behavior.
mod.rs App struct, App::new, and small helpers.
diff --git a/src/tui/screens/help.rs b/src/tui/screens/help.rs
index 1ffeee4..946116d 100644
--- a/src/tui/screens/help.rs
+++ b/src/tui/screens/help.rs
@@ -52,7 +52,7 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState, theme: &Theme) {
]),
Line::from(vec![
Span::styled(" [←] / [→] ", theme.header),
- Span::styled("Jump Page / Move Input Cursor", theme.text),
+ Span::styled("Move Cursor / Switch Details Pane", theme.text),
]),
Line::from(vec![
Span::styled(" [Home] / [End] ", theme.header),
@@ -123,6 +123,10 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState, theme: &Theme) {
Span::styled(" [Ctrl+P] ", theme.header),
Span::styled("Open Addons Manager", theme.text),
]));
+ help_text.push(Line::from(vec![
+ Span::styled(" [←] [→] / [Tab]", theme.header),
+ Span::styled("Switch Details Pane (Seasons/Streams)", theme.text),
+ ]));
help_text.push(Line::from(vec![
Span::styled(" [Enter] ", theme.header),
Span::styled("Select Movie / Play Stream", theme.text),
@@ -172,8 +176,8 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &AppState, theme: &Theme) {
),
]));
help_text.push(Line::from(vec![
- Span::styled(" [Tab] / [S-Tab]", theme.header),
- Span::styled("Next / Previous Details Pane", theme.text),
+ Span::styled(" [←] [→] / [Tab]", theme.header),
+ Span::styled("Switch Details Pane (Audio/Seasons/Streams)", theme.text),
]));
help_text.push(Line::from(vec![
Span::styled(" [Enter] ", theme.header),
diff --git a/src/tui/screens/home.rs b/src/tui/screens/home.rs
index 1a4ee00..39ad91b 100644
--- a/src/tui/screens/home.rs
+++ b/src/tui/screens/home.rs
@@ -850,6 +850,7 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &mut AppState, theme: &Theme)
12
};
let results_area = results_chunk;
+ crate::tui::clear_area(frame, results_area, theme);
let selected_idx = state.search_list_state.selected();
let metrics = state.result_metrics(results_area.height, results_area.width);
@@ -965,6 +966,7 @@ pub fn draw(frame: &mut Frame, area: Rect, state: &mut AppState, theme: &Theme)
frame.render_widget(ratatui_image::Image::new(proto), p_area);
}
}
+ } else {
let is_in_flight = state.in_flight_posters.contains(&res.id);
let placeholder = Paragraph::new(poster_placeholder_lines(
state.basic_terminal,
diff --git a/src/tui/terminal.rs b/src/tui/terminal.rs
index 4dd3c5e..cf88b74 100644
--- a/src/tui/terminal.rs
+++ b/src/tui/terminal.rs
@@ -13,6 +13,9 @@ pub fn should_query_images() -> bool {
{
return false;
}
+ if std::env::var("TMUX").is_ok() && std::env::var("MOVIEBOX_IMAGE_PROTOCOL").is_err() {
+ return false;
+ }
let term = env("TERM");
term != "dumb" && term != "linux"