plex-tui 0.4.0__tar.gz → 0.4.2__tar.gz

{plex_tui-0.4.0 → plex_tui-0.4.2}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.4.2 - 2026-06-18
+
+- Prefer episode stills and season posters for TV artwork while keeping show art
+  as the fallback.
+
+## 0.4.1 - 2026-06-18
+
+- Let explicit `artwork_renderer = "kitty"` try Kitty graphics even when
+  Kitty-specific environment variables are absent, and let `auto` enable the
+  Kitty graphics path in Ghostty.
+
 ## 0.4.0 - 2026-06-17
 
 - Added native Kitty poster artwork via Unicode placeholders for terminals that

{plex_tui-0.4.0 → plex_tui-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plex-tui
-Version: 0.4.0
+Version: 0.4.2
 Summary: A small standalone Plex terminal UI.
 Project-URL: Homepage, https://github.com/so1omon563/plex-tui
 Project-URL: Issues, https://github.com/so1omon563/plex-tui/issues
@@ -247,11 +247,13 @@ presets.
 ## Artwork
 
 Poster artwork renders as portable colored block art by default, so it works in
-ordinary terminals without native image support. In Kitty, set
-`artwork_renderer` to `auto` or `kitty` to render native terminal images through
-Kitty Unicode placeholders. This keeps Textual in charge of layout and redraws
-while Kitty paints the poster inside those cells. Outside Kitty, `auto` falls
-back to block art; `plex-tui --diagnostics` reports the active renderer status.
+ordinary terminals without native image support. In Kitty and Ghostty, set
+`artwork_renderer` to `auto` to render native terminal images through Kitty
+Unicode placeholders. Set `artwork_renderer` to `kitty` to explicitly try the
+Kitty graphics protocol in other compatible terminals. This keeps Textual in
+charge of layout and redraws while the terminal paints the poster inside those
+cells. Outside detected Kitty-compatible terminals, `auto` falls back to block
+art; `plex-tui --diagnostics` reports the active renderer status.
 
 Grid view prefetches artwork for the visible page immediately and, by default,
 prepares three pages ahead in the background. `grid_prefetch_pages` can be set

{plex_tui-0.4.0 → plex_tui-0.4.2}/README.md

@@ -210,11 +210,13 @@ presets.
 ## Artwork
 
 Poster artwork renders as portable colored block art by default, so it works in
-ordinary terminals without native image support. In Kitty, set
-`artwork_renderer` to `auto` or `kitty` to render native terminal images through
-Kitty Unicode placeholders. This keeps Textual in charge of layout and redraws
-while Kitty paints the poster inside those cells. Outside Kitty, `auto` falls
-back to block art; `plex-tui --diagnostics` reports the active renderer status.
+ordinary terminals without native image support. In Kitty and Ghostty, set
+`artwork_renderer` to `auto` to render native terminal images through Kitty
+Unicode placeholders. Set `artwork_renderer` to `kitty` to explicitly try the
+Kitty graphics protocol in other compatible terminals. This keeps Textual in
+charge of layout and redraws while the terminal paints the poster inside those
+cells. Outside detected Kitty-compatible terminals, `auto` falls back to block
+art; `plex-tui --diagnostics` reports the active renderer status.
 
 Grid view prefetches artwork for the visible page immediately and, by default,
 prepares three pages ahead in the background. `grid_prefetch_pages` can be set

{plex_tui-0.4.0 → plex_tui-0.4.2}/ROADMAP.md

@@ -65,5 +65,12 @@
   artwork, pagination, or detail-loading behavior.
 - Revisit whether verbose `PLEX_TUI_ARTWORK_LOG=1` should expose more structured artwork counters.
 - Continue validating Kitty Unicode-placeholder artwork in real terminals.
-  Block art remains the mandatory fallback outside Kitty.
+  Block art remains the mandatory fallback outside known native-image paths.
+- Continue expanding Kitty graphics support beyond Kitty itself after the
+  initial Ghostty path. `artwork_renderer = "kitty"` is the explicit "try Kitty
+  protocol" override, while `auto` should stay conservative until terminal
+  support is verified.
+- Research explicit iTerm inline-image protocol support as a separate renderer
+  path rather than assuming iTerm speaks Kitty graphics. Include WezTerm in that
+  research because its documented image path follows the iTerm image protocol.
 - Add focused regression tests for any real-world Plex media edge cases discovered during use.

{plex_tui-0.4.0 → plex_tui-0.4.2}/config.example.toml

@@ -40,8 +40,9 @@ client_identifier = "plex-tui-your-stable-client-id"
 # Optional artwork settings.
 # artwork_mode can be "on" or "off".
 # artwork_mode = "on"
-# artwork_renderer can be "block", "auto", or "kitty". Auto uses native Kitty
-# images when Kitty is detected, otherwise it falls back to block art.
+# artwork_renderer can be "block", "auto", or "kitty". Auto uses Kitty graphics
+# in detected compatible terminals such as Kitty and Ghostty, otherwise it falls
+# back to block art. "kitty" explicitly tries the Kitty graphics protocol.
 # artwork_renderer = "block"
 # detail_artwork_mode can be "list_only", "on", or "off".
 # detail_artwork_mode = "list_only"

{plex_tui-0.4.0 → plex_tui-0.4.2}/packaging/aur/.SRCINFO

@@ -1,6 +1,6 @@
 pkgbase = plex-tui
 	pkgdesc = Standalone Plex terminal UI with mpv playback
-	pkgver = 0.3.43
+	pkgver = 0.4.1
 	pkgrel = 1
 	url = https://github.com/so1omon563/plex-tui
 	arch = any
@@ -16,7 +16,7 @@ pkgbase = plex-tui
 	depends = python-plexapi
 	depends = python-rich
 	depends = python-textual
-	source = plex-tui-0.3.43.tar.gz::https://github.com/so1omon563/plex-tui/archive/refs/tags/v0.3.43.tar.gz
-	sha256sums = 7e034f82945a4645fd01364c79b1d9bfd2d7820257aef4012eaf9ce5d3e9aa58
+	source = plex-tui-0.4.1.tar.gz::https://github.com/so1omon563/plex-tui/archive/refs/tags/v0.4.1.tar.gz
+	sha256sums = 2271c6413ec204ba1250b812e6b9e98af37afaeb44006d5c17fb0f82cf419282
 
 pkgname = plex-tui

{plex_tui-0.4.0 → plex_tui-0.4.2}/packaging/aur/PKGBUILD

@@ -1,6 +1,6 @@
 # Maintainer: so1omon
 pkgname=plex-tui
-pkgver=0.3.43
+pkgver=0.4.1
 pkgrel=1
 pkgdesc="Standalone Plex terminal UI with mpv playback"
 arch=("any")
@@ -22,7 +22,7 @@ makedepends=(
   "python-wheel"
 )
 source=("$pkgname-$pkgver.tar.gz::$url/archive/refs/tags/v$pkgver.tar.gz")
-sha256sums=("7e034f82945a4645fd01364c79b1d9bfd2d7820257aef4012eaf9ce5d3e9aa58")
+sha256sums=("2271c6413ec204ba1250b812e6b9e98af37afaeb44006d5c17fb0f82cf419282")
 
 build() {
   cd "$pkgname-$pkgver"

{plex_tui-0.4.0 → plex_tui-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plex-tui"
-version = "0.4.0"
+version = "0.4.2"
 description = "A small standalone Plex terminal UI."
 readme = "README.md"
 license = "MIT"

{plex_tui-0.4.0 → plex_tui-0.4.2}/src/plextui/__init__.py

@@ -1,3 +1,3 @@
 """Plex TUI prototype."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"

{plex_tui-0.4.0 → plex_tui-0.4.2}/src/plextui/artwork.py

@@ -210,7 +210,7 @@ def render_protocol_artwork(data: bytes, renderer: str, width: int = 28, max_hei
 
 
 def resolve_protocol_renderer(renderer: str) -> str:
-    if renderer == "kitty" and kitty_graphics_supported():
+    if renderer == "kitty":
         return "kitty"
     if renderer == "auto" and kitty_graphics_supported():
         return "kitty"
@@ -222,20 +222,28 @@ def protocol_renderer_status(renderer: str) -> str:
     if resolved == "kitty":
         return "Kitty native images via Unicode placeholders"
     if renderer == "auto":
-        return "Block art; Kitty terminal not detected"
+        return "Block art; Kitty-compatible terminal not detected"
     if renderer == "kitty":
-        return "Block fallback; Kitty terminal not detected"
+        return "Kitty native images via Unicode placeholders"
     return "Block art"
 
 
 def kitty_graphics_supported() -> bool:
-    return bool(os.environ.get("KITTY_WINDOW_ID") or os.environ.get("KITTY_PID"))
+    return bool(os.environ.get("KITTY_WINDOW_ID") or os.environ.get("KITTY_PID") or ghostty_terminal_detected())
+
+
+def ghostty_terminal_detected() -> bool:
+    term_program = os.environ.get("TERM_PROGRAM", "").lower()
+    term = os.environ.get("TERM", "").lower()
+    return term_program == "ghostty" or term.startswith("xterm-ghostty")
 
 
 def kitty_environment_status() -> str:
     fields = [
         f"KITTY_WINDOW_ID={int(bool(os.environ.get('KITTY_WINDOW_ID')))}",
         f"KITTY_PID={int(bool(os.environ.get('KITTY_PID')))}",
+        f"TERM_PROGRAM={os.environ.get('TERM_PROGRAM', '')!r}",
+        f"TERM_PROGRAM_VERSION={os.environ.get('TERM_PROGRAM_VERSION', '')!r}",
         f"TERM={os.environ.get('TERM', '')!r}",
         f"COLORTERM={os.environ.get('COLORTERM', '')!r}",
     ]

{plex_tui-0.4.0 → plex_tui-0.4.2}/src/plextui/plex_service.py

@@ -226,7 +226,13 @@ def media_details(item: MediaItem) -> MediaDetails:
 
 
 def artwork_path(raw: Any) -> str:
-    for attr in ("grandparentThumb", "parentThumb", "thumb", "art"):
+    kind = str(getattr(raw, "TYPE", raw.__class__.__name__)).lower()
+    attrs = (
+        ("thumb", "parentThumb", "grandparentThumb", "art")
+        if kind in {"show", "season", "episode"}
+        else ("grandparentThumb", "parentThumb", "thumb", "art")
+    )
+    for attr in attrs:
         value = getattr(raw, attr, None)
         if value:
             return str(value)

{plex_tui-0.4.0 → plex_tui-0.4.2}/tests/test_artwork.py

@@ -80,16 +80,20 @@ def test_render_artwork_returns_halfcell_text():
     assert rendered.spans
 
 
-def test_render_protocol_artwork_falls_back_without_explicit_native_opt_in(monkeypatch):
+def test_render_protocol_artwork_tries_kitty_when_explicitly_enabled(monkeypatch):
     monkeypatch.delenv("KITTY_WINDOW_ID", raising=False)
     monkeypatch.delenv("KITTY_PID", raising=False)
+    monkeypatch.delenv("TERM_PROGRAM", raising=False)
+    transmitted = []
+    monkeypatch.setattr(artwork, "emit_kitty_graphics_commands", lambda commands: transmitted.extend(commands))
     image = Image.new("RGB", (2, 4), "#00ff00")
     buffer = BytesIO()
     image.save(buffer, format="PNG")
 
     rendered = render_protocol_artwork(buffer.getvalue(), "kitty", width=2, max_height=2)
 
-    assert rendered is None
+    assert isinstance(rendered, KittyImage)
+    assert transmitted == list(rendered.commands)
 
 
 def test_render_protocol_artwork_uses_unicode_placeholders_when_kitty_is_detected(monkeypatch):
@@ -136,6 +140,7 @@ def test_kitty_graphics_commands_chunks_large_payload(monkeypatch):
 def test_auto_protocol_renderer_requires_kitty_terminal(monkeypatch):
     monkeypatch.delenv("KITTY_WINDOW_ID", raising=False)
     monkeypatch.delenv("KITTY_PID", raising=False)
+    monkeypatch.delenv("TERM_PROGRAM", raising=False)
     monkeypatch.setenv("TERM", "xterm-256color")
     image = Image.new("RGB", (2, 4), "#00ff00")
     buffer = BytesIO()
@@ -144,14 +149,32 @@ def test_auto_protocol_renderer_requires_kitty_terminal(monkeypatch):
     rendered = render_protocol_artwork(buffer.getvalue(), "auto", width=2, max_height=2)
 
     assert rendered is None
-    assert protocol_renderer_status("auto") == "Block art; Kitty terminal not detected"
+    assert protocol_renderer_status("auto") == "Block art; Kitty-compatible terminal not detected"
+
+
+def test_auto_protocol_renderer_uses_kitty_placeholders_in_ghostty(monkeypatch):
+    monkeypatch.delenv("KITTY_WINDOW_ID", raising=False)
+    monkeypatch.delenv("KITTY_PID", raising=False)
+    monkeypatch.setenv("TERM_PROGRAM", "ghostty")
+    transmitted = []
+    monkeypatch.setattr(artwork, "emit_kitty_graphics_commands", lambda commands: transmitted.extend(commands))
+    image = Image.new("RGB", (2, 4), "#00ff00")
+    buffer = BytesIO()
+    image.save(buffer, format="PNG")
+
+    rendered = render_protocol_artwork(buffer.getvalue(), "auto", width=2, max_height=2)
 
+    assert isinstance(rendered, KittyImage)
+    assert transmitted == list(rendered.commands)
+    assert protocol_renderer_status("auto") == "Kitty native images via Unicode placeholders"
 
-def test_protocol_renderer_status_explains_textual_fallback(monkeypatch):
+
+def test_protocol_renderer_status_explains_explicit_kitty_force(monkeypatch):
     monkeypatch.delenv("KITTY_WINDOW_ID", raising=False)
     monkeypatch.delenv("KITTY_PID", raising=False)
+    monkeypatch.delenv("TERM_PROGRAM", raising=False)
 
-    assert protocol_renderer_status("kitty") == "Block fallback; Kitty terminal not detected"
+    assert protocol_renderer_status("kitty") == "Kitty native images via Unicode placeholders"
 
 
 def test_kitty_placeholder_lines_encode_row_and_column_cells():

{plex_tui-0.4.0 → plex_tui-0.4.2}/tests/test_plex_service.py

@@ -1,7 +1,16 @@
 from __future__ import annotations
 
 from plextui.models import LibraryItem, MediaItem
-from plextui.plex_service import PlexService, kind_label, media_details, progress_label, row_progress_marker, watched_state
+from plextui.plex_service import (
+    PlexService,
+    artwork_path,
+    kind_label,
+    media_details,
+    progress_label,
+    row_progress_marker,
+    to_media_item,
+    watched_state,
+)
 
 
 class RawItem:
@@ -62,6 +71,18 @@ class DetailedRawItem(RawItem):
         return [Part()]
 
 
+class TvEpisodeRawItem(DetailedRawItem):
+    TYPE = "episode"
+    title = "Episode"
+    thumb = "/library/metadata/episode/thumb"
+
+
+class TvSeasonRawItem(DetailedRawItem):
+    TYPE = "season"
+    title = "Season 1"
+    thumb = "/library/metadata/season-own/thumb"
+
+
 class RawPage(list):
     totalSize = 250
 
@@ -219,6 +240,32 @@ def test_media_details_include_audio_and_subtitle_locations():
     assert details.artwork_path == "/library/metadata/show/thumb"
 
 
+def test_tv_episode_artwork_prefers_episode_still():
+    assert artwork_path(TvEpisodeRawItem()) == "/library/metadata/episode/thumb"
+    assert to_media_item(TvEpisodeRawItem()).artwork_path == "/library/metadata/episode/thumb"
+
+
+def test_tv_season_artwork_prefers_season_poster():
+    assert artwork_path(TvSeasonRawItem()) == "/library/metadata/season-own/thumb"
+    assert to_media_item(TvSeasonRawItem()).artwork_path == "/library/metadata/season-own/thumb"
+
+
+def test_tv_artwork_falls_back_to_parent_then_show_art():
+    class EpisodeWithoutStill(TvEpisodeRawItem):
+        thumb = ""
+
+    class SeasonWithoutPoster(TvSeasonRawItem):
+        thumb = ""
+
+    class EpisodeWithoutSeasonArt(TvEpisodeRawItem):
+        thumb = ""
+        parentThumb = ""
+
+    assert artwork_path(EpisodeWithoutStill()) == "/library/metadata/season/thumb"
+    assert artwork_path(SeasonWithoutPoster()) == "/library/metadata/season/thumb"
+    assert artwork_path(EpisodeWithoutSeasonArt()) == "/library/metadata/show/thumb"
+
+
 def test_kind_label_humanizes_known_and_unknown_media_types():
     assert kind_label("movie") == "Movie"
     assert kind_label("show") == "TV Show"