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

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

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.4.0 - 2026-06-17
+
+- Added native Kitty poster artwork via Unicode placeholders for terminals that
+  advertise Kitty graphics support, with higher-resolution native image fetches
+  and block art kept as the fallback.
+
+## 0.3.43 - 2026-06-16
+
+- Kept the footer command bar focused on core actions while leaving the full
+  keyboard reference discoverable from Help.
+
 ## 0.3.41 - 2026-06-16
 
 - Fixed Plex-transcoded resume playback by passing the resume offset into the

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plex-tui
-Version: 0.3.41
+Version: 0.4.0
 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
@@ -246,12 +246,12 @@ presets.
 
 ## Artwork
 
-Poster artwork renders as portable colored block art, so it works in ordinary
-terminals without Kitty, iTerm2, or Sixel support. Native Kitty image output is
-disabled inside the Textual app because direct Kitty graphics protocol placement
-can destabilize the UI. If `artwork_renderer` is set to `auto` or `kitty`, the
-app falls back to block art and summarizes the fallback in
-`plex-tui --diagnostics`.
+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.
 
 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.3.41 → plex_tui-0.4.0}/README.md

@@ -209,12 +209,12 @@ presets.
 
 ## Artwork
 
-Poster artwork renders as portable colored block art, so it works in ordinary
-terminals without Kitty, iTerm2, or Sixel support. Native Kitty image output is
-disabled inside the Textual app because direct Kitty graphics protocol placement
-can destabilize the UI. If `artwork_renderer` is set to `auto` or `kitty`, the
-app falls back to block art and summarizes the fallback in
-`plex-tui --diagnostics`.
+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.
 
 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.3.41 → plex_tui-0.4.0}/ROADMAP.md

@@ -64,9 +64,6 @@
 - Use `PLEX_TUI_PERF_LOG=1` for focused regression checks when changing grid,
   artwork, pagination, or detail-loading behavior.
 - Revisit whether verbose `PLEX_TUI_ARTWORK_LOG=1` should expose more structured artwork counters.
-- Revisit native terminal image support with a Kitty Unicode-placeholder
-  prototype. Direct Kitty graphics protocol placement inside Textual caused UI
-  hangs, so any future implementation should transmit images quietly, render
-  normal placeholder text that Textual can redraw safely, and keep block art as
-  the mandatory fallback.
+- Continue validating Kitty Unicode-placeholder artwork in real terminals.
+  Block art remains the mandatory fallback outside Kitty.
 - Add focused regression tests for any real-world Plex media edge cases discovered during use.

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

@@ -40,8 +40,8 @@ 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/kitty currently
-# fall back to block art because direct Kitty image placement is unsafe in Textual.
+# 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 = "block"
 # detail_artwork_mode can be "list_only", "on", or "off".
 # detail_artwork_mode = "list_only"

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

@@ -1,6 +1,6 @@
 pkgbase = plex-tui
 	pkgdesc = Standalone Plex terminal UI with mpv playback
-	pkgver = 0.3.39
+	pkgver = 0.3.43
 	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.39.tar.gz::https://github.com/so1omon563/plex-tui/archive/refs/tags/v0.3.39.tar.gz
-	sha256sums = 1e799c3f9635dc8e36b1da8ace89a1c3776fb9414a40e74c635f803864c48fad
+	source = plex-tui-0.3.43.tar.gz::https://github.com/so1omon563/plex-tui/archive/refs/tags/v0.3.43.tar.gz
+	sha256sums = 7e034f82945a4645fd01364c79b1d9bfd2d7820257aef4012eaf9ce5d3e9aa58
 
 pkgname = plex-tui

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

@@ -1,6 +1,6 @@
 # Maintainer: so1omon
 pkgname=plex-tui
-pkgver=0.3.39
+pkgver=0.3.43
 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=("1e799c3f9635dc8e36b1da8ace89a1c3776fb9414a40e74c635f803864c48fad")
+sha256sums=("7e034f82945a4645fd01364c79b1d9bfd2d7820257aef4012eaf9ce5d3e9aa58")
 
 build() {
   cd "$pkgname-$pkgver"

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

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

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

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

{plex_tui-0.3.41 → plex_tui-0.4.0}/src/plextui/app.py

@@ -26,7 +26,16 @@ from textual.timer import Timer
 from textual.widgets import Footer, Header, Input, Label, ListItem, ListView, Static
 
 from . import __version__
-from .artwork import artwork_is_cached, fetch_artwork, protocol_renderer_status, render_artwork, render_protocol_artwork
+from .artwork import (
+    KittyImage,
+    artwork_is_cached,
+    fetch_artwork,
+    kitty_pixel_size,
+    protocol_renderer_status,
+    render_artwork,
+    render_protocol_artwork,
+    resolve_protocol_renderer,
+)
 from .auth import LoginSession, ServerChoice, save_server_choice
 from .config import (
     DEFAULT_AUTO_LOAD_THRESHOLD,
@@ -431,29 +440,39 @@ class PlexTuiApp(App[None]):
 
     BINDINGS = [
         Binding("q", "quit", "Quit"),
-        Binding("ctrl+r", "reload", "Reload"),
+        Binding("ctrl+r", "reload", "Reload", show=False),
         Binding("/", "focus_search", "Search"),
         Binding("g", "focus_global_search", "Global"),
-        Binding("tab", "focus_next", "Next"),
-        Binding("shift+tab", "focus_previous", "Prev"),
+        Binding("tab", "focus_next", "Next", show=False),
+        Binding("shift+tab", "focus_previous", "Prev", show=False),
         Binding("question_mark", "show_help", "Help"),
-        Binding("l", "focus_libraries", "Focus libraries"),
-        Binding("m", "focus_media", "Focus media list"),
-        Binding("d", "focus_details", "Focus details"),
+        Binding("l", "focus_libraries", "Focus libraries", show=False),
+        Binding("m", "focus_media", "Focus media list", show=False),
+        Binding("d", "focus_details", "Focus details", show=False),
         Binding("v", "toggle_media_view", "View"),
-        Binding("left_square_bracket", "jump_alpha_previous", "Prev letter"),
-        Binding("right_square_bracket", "jump_alpha_next", "Next letter"),
-        Binding("left", "grid_left", "Left"),
-        Binding("right", "grid_right", "Right"),
+        Binding(
+            "left_square_bracket",
+            "jump_alpha_previous",
+            "Prev letter",
+            show=False,
+        ),
+        Binding(
+            "right_square_bracket",
+            "jump_alpha_next",
+            "Next letter",
+            show=False,
+        ),
+        Binding("left", "grid_left", "Left", show=False),
+        Binding("right", "grid_right", "Right", show=False),
         Binding("comma", "show_settings", "Settings"),
         Binding("escape", "back_or_clear", "Back"),
         Binding("p", "play_selected", "Play"),
         Binding("r", "resume_selected", "Resume"),
-        Binding("a", "audio_picker", "Audio"),
-        Binding("s", "subtitle_picker", "Subtitles"),
-        Binding("A", "clear_audio_preference", "Clear audio"),
-        Binding("S", "cycle_subtitle_mode", "Sub mode"),
-        Binding("x", "stop_playback", "Stop"),
+        Binding("a", "audio_picker", "Audio", show=False),
+        Binding("s", "subtitle_picker", "Subtitles", show=False),
+        Binding("A", "clear_audio_preference", "Clear audio", show=False),
+        Binding("S", "cycle_subtitle_mode", "Sub mode", show=False),
+        Binding("x", "stop_playback", "Stop", show=False),
     ]
 
     service: reactive[PlexService | None] = reactive(None)
@@ -1187,8 +1206,9 @@ class PlexTuiApp(App[None]):
             artwork_path = getattr(details, "artwork_path")
             if detail_size is not None:
                 width, height = detail_size
+                fetch_width, fetch_height = artwork_fetch_pixel_size(self.config, width, height)
                 detail_fetch_started = time.perf_counter()
-                data = fetch_artwork(full_item.raw, artwork_path, self.config, width=width, height=height * 2)
+                data = fetch_artwork(full_item.raw, artwork_path, self.config, width=fetch_width, height=fetch_height)
                 detail_fetch_ms = (time.perf_counter() - detail_fetch_started) * 1000
                 detail_render_started = time.perf_counter()
                 artwork = (
@@ -1202,7 +1222,7 @@ class PlexTuiApp(App[None]):
                 if card_artwork is not None:
                     card_cache_hit = True
                 else:
-                    card_width, card_height = card_artwork_pixel_size(self.config)
+                    card_width, card_height = card_artwork_fetch_size(self.config)
                     card_fetch_started = time.perf_counter()
                     card_data = fetch_artwork(
                         full_item.raw,
@@ -1505,7 +1525,7 @@ class PlexTuiApp(App[None]):
         failed_count = 0
         try:
             prefetch_items = [item for item in items if item.artwork_path]
-            width, height = card_artwork_pixel_size(self.config)
+            width, height = card_artwork_fetch_size(self.config)
             cached_count = sum(
                 1 for item in prefetch_items if artwork_is_cached(item.artwork_path, self.config, width=width, height=height)
             )
@@ -2570,6 +2590,13 @@ def grid_card_line(value: str, width: int, style: str) -> Text:
 
 
 def center_renderable_lines(renderable: object, width: int) -> object:
+    if isinstance(renderable, KittyImage):
+        plain_width = renderable.columns + renderable.left_padding + renderable.right_padding
+        if plain_width >= width:
+            return renderable.copy()
+        left = (width - plain_width) // 2
+        right = width - plain_width - left
+        return renderable.padded(left, right)
     if isinstance(renderable, Group):
         return Group(*(center_renderable_lines(item, width) for item in renderable.renderables))
     if isinstance(renderable, Text):
@@ -2598,7 +2625,12 @@ def copy_renderable(renderable: object | None) -> object | None:
 
 def render_card_artwork(data: bytes, config: AppConfig) -> object:
     spec = grid_density_spec(config)
-    artwork = render_artwork(data, width=int(spec["art_width"]), max_height=int(spec["art_height"]))
+    width = int(spec["art_width"])
+    height = int(spec["art_height"])
+    protocol_artwork = render_protocol_artwork(data, config.artwork_renderer, width=width, max_height=height)
+    if protocol_artwork is not None:
+        return protocol_artwork
+    artwork = render_artwork(data, width=width, max_height=height)
     return Group(*artwork.split("\n"))
 
 
@@ -2607,8 +2639,21 @@ def card_artwork_pixel_size(config: AppConfig) -> tuple[int, int]:
     return int(spec["art_width"]), int(spec["art_height"]) * 2
 
 
-def grid_artwork_cache_key(item: MediaItem, config: AppConfig) -> tuple[str, str]:
-    return item.artwork_path, config.grid_density
+def card_artwork_fetch_size(config: AppConfig) -> tuple[int, int]:
+    spec = grid_density_spec(config)
+    width = int(spec["art_width"])
+    height = int(spec["art_height"])
+    return artwork_fetch_pixel_size(config, width, height)
+
+
+def artwork_fetch_pixel_size(config: AppConfig, width: int, height: int) -> tuple[int, int]:
+    if resolve_protocol_renderer(config.artwork_renderer) == "kitty":
+        return kitty_pixel_size(width, height)
+    return width, height * 2
+
+
+def grid_artwork_cache_key(item: MediaItem, config: AppConfig) -> tuple[str, str, str]:
+    return item.artwork_path, config.grid_density, config.artwork_renderer
 
 
 def grid_density_spec(config: AppConfig | None) -> dict[str, int]:

plex_tui-0.4.0/src/plextui/artwork.py

@@ -0,0 +1,407 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import sys
+import threading
+from dataclasses import dataclass, replace
+from io import BytesIO
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode, urlsplit, urlunsplit
+from urllib.request import Request, urlopen
+
+from PIL import Image, ImageOps
+from rich.measure import Measurement
+from rich.segment import Segment
+from rich.style import Style
+from rich.text import Text
+
+from .config import AppConfig, cache_path, write_debug_log
+
+
+MAX_IMAGE_BYTES = 12 * 1024 * 1024
+ARTWORK_CACHE_LIMIT_BYTES = 100 * 1024 * 1024
+KITTY_PAYLOAD_CHUNK_SIZE = 4096
+KITTY_CELL_WIDTH_PX = 12
+KITTY_CELL_HEIGHT_PX = 24
+KITTY_TRANSMIT_LOCK = threading.Lock()
+KITTY_PLACEHOLDER = "\U0010eeee"
+KITTY_PLACEHOLDER_DIACRITICS = tuple(chr(codepoint) for codepoint in (
+    0x0305, 0x030D, 0x030E, 0x0310, 0x0312, 0x033D, 0x033E, 0x033F,
+    0x0346, 0x034A, 0x034B, 0x034C, 0x0350, 0x0351, 0x0352, 0x0357,
+    0x035B, 0x0363, 0x0364, 0x0365, 0x0366, 0x0367, 0x0368, 0x0369,
+    0x036A, 0x036B, 0x036C, 0x036D, 0x036E, 0x036F, 0x0483, 0x0484,
+    0x0485, 0x0486, 0x0487, 0x0592, 0x0593, 0x0594, 0x0595, 0x0597,
+))
+
+
+@dataclass(frozen=True)
+class KittyImage:
+    commands: tuple[str, ...]
+    lines: tuple[str, ...]
+    image_id: int
+    columns: int
+    left_padding: int = 0
+    right_padding: int = 0
+
+    @property
+    def plain(self) -> str:
+        padding_left = " " * self.left_padding
+        padding_right = " " * self.right_padding
+        return "\n".join(f"{padding_left}{line}{padding_right}" for line in self.lines)
+
+    def copy(self) -> "KittyImage":
+        return self
+
+    def padded(self, left: int, right: int) -> "KittyImage":
+        return replace(
+            self,
+            left_padding=self.left_padding + max(0, left),
+            right_padding=self.right_padding + max(0, right),
+        )
+
+    def __rich_console__(self, console: object, options: object) -> object:
+        del console, options
+        style = Style(color=f"#{self.image_id:06x}")
+        left = " " * self.left_padding
+        right = " " * self.right_padding
+        for index, line in enumerate(self.lines):
+            if left:
+                yield Segment(left)
+            yield Segment(line, style)
+            if right:
+                yield Segment(right)
+            if index < len(self.lines) - 1:
+                yield Segment.line()
+
+    def __rich_measure__(self, console: object, options: object) -> Measurement:
+        del console, options
+        width = self.left_padding + self.columns + self.right_padding
+        return Measurement(width, width)
+
+
+def fetch_artwork(raw: Any, path: str, config: AppConfig, width: int | None = None, height: int | None = None) -> bytes:
+    cached = cached_artwork_path(path, config, width, height)
+    if cached.exists():
+        return cached.read_bytes()
+
+    url = artwork_url(raw, path, config, width, height)
+    request = Request(url, headers={"User-Agent": "plex-tui"})
+    with urlopen(request, timeout=10) as response:
+        status = getattr(response, "status", 200)
+        if status != 200:
+            raise OSError(f"artwork fetch failed: HTTP {status}")
+        data = response.read(MAX_IMAGE_BYTES + 1)
+    if len(data) > MAX_IMAGE_BYTES:
+        raise OSError("artwork image is too large")
+
+    cached.parent.mkdir(parents=True, exist_ok=True)
+    cached.write_bytes(data)
+    prune_artwork_cache()
+    return data
+
+
+def artwork_url(raw: Any, path: str, config: AppConfig, width: int | None = None, height: int | None = None) -> str:
+    if width is not None and height is not None:
+        return transcode_artwork_url(path, config, width, height)
+
+    server = getattr(raw, "_server", None)
+    if server is not None and hasattr(server, "url"):
+        try:
+            return str(server.url(path, includeToken=True))
+        except Exception:
+            pass
+
+    if path.startswith("http://") or path.startswith("https://"):
+        url = path
+    else:
+        url = f"{config.base_url.rstrip('/')}/{path.lstrip('/')}"
+    return add_token(url, config.token)
+
+
+def transcode_artwork_url(path: str, config: AppConfig, width: int, height: int) -> str:
+    base_url = config.base_url.rstrip("/")
+    query = urlencode({
+        "width": max(1, width),
+        "height": max(1, height),
+        "minSize": 1,
+        "upscale": 1,
+        "url": path,
+    })
+    return add_token(f"{base_url}/photo/:/transcode?{query}", config.token)
+
+
+def add_token(url: str, token: str) -> str:
+    if not token:
+        return url
+    parts = urlsplit(url)
+    query = parts.query
+    separator = "&" if query else ""
+    query = f"{query}{separator}{urlencode({'X-Plex-Token': token})}"
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, query, parts.fragment))
+
+
+def cached_artwork_path(path: str, config: AppConfig, width: int | None = None, height: int | None = None) -> Path:
+    source = f"{config.base_url}\0{path}"
+    if width is not None or height is not None:
+        source = f"{source}\0{width or ''}x{height or ''}"
+    key = hashlib.sha256(source.encode("utf-8")).hexdigest()
+    return cache_path() / "artwork" / f"{key}.img"
+
+
+def artwork_is_cached(path: str, config: AppConfig, width: int | None = None, height: int | None = None) -> bool:
+    return cached_artwork_path(path, config, width, height).exists()
+
+
+def prune_artwork_cache(limit_bytes: int = ARTWORK_CACHE_LIMIT_BYTES) -> None:
+    directory = cache_path() / "artwork"
+    if not directory.exists():
+        return
+    files = []
+    total = 0
+    try:
+        for path in directory.iterdir():
+            if not path.is_file():
+                continue
+            stat = path.stat()
+            files.append((stat.st_mtime, stat.st_size, path))
+            total += stat.st_size
+    except OSError:
+        return
+    if total <= limit_bytes:
+        return
+    for _, size, path in sorted(files):
+        try:
+            path.unlink()
+        except OSError:
+            continue
+        total -= size
+        if total <= limit_bytes:
+            break
+
+
+def render_artwork(data: bytes, width: int = 28, max_height: int = 20) -> Text:
+    image = load_image(data)
+    image = resize_for_cells(image, width, max_height)
+
+    text = Text()
+    pixels = image.load()
+    for y in range(0, image.height, 2):
+        for x in range(image.width):
+            top = pixels[x, y]
+            bottom = pixels[x, y + 1] if y + 1 < image.height else top
+            text.append("▀", style=f"{rgb(top)} on {rgb(bottom)}")
+        if y + 2 < image.height:
+            text.append("\n")
+    return text
+
+
+def render_protocol_artwork(data: bytes, renderer: str, width: int = 28, max_height: int = 20) -> object | None:
+    resolved = resolve_protocol_renderer(renderer)
+    if resolved != "kitty":
+        write_kitty_artwork_log(
+            f"kitty renderer skipped requested={renderer!r} resolved={resolved!r} "
+            f"env={kitty_environment_status()}"
+        )
+        return None
+    return render_kitty_artwork(data, width=width, max_height=max_height, transmit=True)
+
+
+def resolve_protocol_renderer(renderer: str) -> str:
+    if renderer == "kitty" and kitty_graphics_supported():
+        return "kitty"
+    if renderer == "auto" and kitty_graphics_supported():
+        return "kitty"
+    return "block"
+
+
+def protocol_renderer_status(renderer: str) -> str:
+    resolved = resolve_protocol_renderer(renderer)
+    if resolved == "kitty":
+        return "Kitty native images via Unicode placeholders"
+    if renderer == "auto":
+        return "Block art; Kitty terminal not detected"
+    if renderer == "kitty":
+        return "Block fallback; Kitty terminal not detected"
+    return "Block art"
+
+
+def kitty_graphics_supported() -> bool:
+    return bool(os.environ.get("KITTY_WINDOW_ID") or os.environ.get("KITTY_PID"))
+
+
+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={os.environ.get('TERM', '')!r}",
+        f"COLORTERM={os.environ.get('COLORTERM', '')!r}",
+    ]
+    return ",".join(fields)
+
+
+def render_kitty_artwork(data: bytes, width: int = 28, max_height: int = 20, transmit: bool = False) -> KittyImage:
+    image = load_image(data)
+    columns, rows = kitty_cell_dimensions(image, width, max_height)
+    image = resize_for_kitty_cells(image, columns, rows)
+    buffer = BytesIO()
+    image.save(buffer, format="PNG")
+    payload = base64.b64encode(buffer.getvalue()).decode("ascii")
+    image_id = kitty_image_id(buffer.getvalue(), columns, rows)
+    commands = kitty_graphics_commands(payload, image_id=image_id, columns=columns, rows=rows)
+    if transmit:
+        emit_kitty_graphics_commands(commands)
+    return KittyImage(
+        commands=tuple(commands),
+        lines=tuple(kitty_placeholder_lines(image_id, columns, rows)),
+        image_id=image_id,
+        columns=columns,
+    )
+
+
+def kitty_pixel_size(width: int, max_height: int) -> tuple[int, int]:
+    return max(1, width) * KITTY_CELL_WIDTH_PX, max(1, max_height) * KITTY_CELL_HEIGHT_PX
+
+
+def kitty_cell_dimensions(image: Image.Image, width: int, max_height: int) -> tuple[int, int]:
+    source_width, source_height = image.size
+    width = max(1, width)
+    max_height = max(1, max_height)
+    if not source_width or not source_height:
+        return 1, 1
+    rows = min(max_height, max(1, round(source_height / source_width * width)))
+    return width, rows
+
+
+def kitty_graphics_commands(
+    payload: str,
+    image_id: int | None = None,
+    columns: int | None = None,
+    rows: int | None = None,
+) -> list[str]:
+    placement = ""
+    if image_id is not None:
+        placement = f",i={image_id},U=1,c={max(1, columns or 1)},r={max(1, rows or 1)}"
+    chunks = [
+        payload[index : index + KITTY_PAYLOAD_CHUNK_SIZE]
+        for index in range(0, len(payload), KITTY_PAYLOAD_CHUNK_SIZE)
+    ]
+    if not chunks:
+        return [f"\033_Ga=T,f=100,q=2{placement};\033\\"]
+    if len(chunks) == 1:
+        return [f"\033_Ga=T,f=100,q=2{placement};{chunks[0]}\033\\"]
+
+    commands = []
+    for index, chunk in enumerate(chunks):
+        if index == 0:
+            prefix = f"a=T,f=100,q=2{placement},m=1"
+        elif index == len(chunks) - 1:
+            prefix = "m=0"
+        else:
+            prefix = "m=1"
+        commands.append(f"\033_G{prefix};{chunk}\033\\")
+    return commands
+
+
+def emit_kitty_graphics_commands(commands: list[str]) -> None:
+    payload = "".join(commands).encode("ascii")
+    with KITTY_TRANSMIT_LOCK:
+        emit_kitty_graphics_payload(payload)
+
+
+def emit_kitty_graphics_payload(payload: bytes) -> None:
+    target = "none"
+    try:
+        fd = os.open("/dev/tty", os.O_WRONLY | os.O_NOCTTY)
+    except OSError:
+        fd = None
+    if fd is not None:
+        try:
+            write_all(fd, payload)
+            target = "/dev/tty"
+            return
+        except OSError:
+            target = "/dev/tty-failed"
+        finally:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+            write_kitty_artwork_log(f"kitty transmit bytes={len(payload)} target={target}")
+    try:
+        stdout = getattr(sys, "__stdout__", sys.stdout)
+        buffer = getattr(stdout, "buffer", None)
+        if buffer is not None:
+            buffer.write(payload)
+            buffer.flush()
+        else:
+            stdout.write(payload.decode("ascii"))
+            stdout.flush()
+        target = "__stdout__"
+    except OSError:
+        target = "__stdout__-failed"
+    finally:
+        write_kitty_artwork_log(f"kitty transmit bytes={len(payload)} target={target}")
+
+
+def write_all(fd: int, payload: bytes) -> None:
+    view = memoryview(payload)
+    written = 0
+    while written < len(payload):
+        count = os.write(fd, view[written:])
+        if count <= 0:
+            raise OSError("short write to terminal")
+        written += count
+
+
+def kitty_image_id(data: bytes, columns: int, rows: int) -> int:
+    digest = hashlib.sha256(data + f"\0{columns}x{rows}".encode("ascii")).digest()
+    return int.from_bytes(digest[:3], "big") or 1
+
+
+def kitty_placeholder_lines(image_id: int, columns: int, rows: int) -> list[str]:
+    if columns >= len(KITTY_PLACEHOLDER_DIACRITICS) or rows >= len(KITTY_PLACEHOLDER_DIACRITICS):
+        raise ValueError("Kitty placeholder dimensions exceed supported diacritics")
+    high_byte = image_id >> 24
+    high = KITTY_PLACEHOLDER_DIACRITICS[high_byte] if high_byte else ""
+    lines = []
+    for row in range(rows):
+        row_mark = KITTY_PLACEHOLDER_DIACRITICS[row]
+        cells = [
+            f"{KITTY_PLACEHOLDER}{row_mark}{KITTY_PLACEHOLDER_DIACRITICS[column]}{high}"
+            for column in range(columns)
+        ]
+        lines.append("".join(cells))
+    return lines
+
+
+def write_kitty_artwork_log(message: str) -> None:
+    if os.environ.get("PLEX_TUI_ARTWORK_LOG") != "1":
+        return
+    write_debug_log(message)
+
+
+def load_image(data: bytes) -> Image.Image:
+    return ImageOps.exif_transpose(Image.open(BytesIO(data))).convert("RGB")
+
+
+def resize_for_cells(image: Image.Image, width: int, max_height: int) -> Image.Image:
+    source_width, source_height = image.size
+    if not source_width or not source_height:
+        return Image.new("RGB", (1, 2), "#000000")
+
+    width = max(1, width)
+    max_height = max(1, max_height)
+    pixel_height = min(max_height * 2, max(2, round(source_height / source_width * width * 2)))
+    return ImageOps.contain(image, (width, pixel_height), Image.Resampling.LANCZOS)
+
+
+def resize_for_kitty_cells(image: Image.Image, width: int, max_height: int) -> Image.Image:
+    max_width_px, max_height_px = kitty_pixel_size(width, max_height)
+    return ImageOps.contain(image, (max_width_px, max_height_px), Image.Resampling.LANCZOS)
+
+
+def rgb(color: tuple[int, int, int]) -> str:
+    return f"#{color[0]:02x}{color[1]:02x}{color[2]:02x}"

{plex_tui-0.3.41 → plex_tui-0.4.0}/tests/test_app_helpers.py

@@ -9,6 +9,7 @@ from rich.align import Align
 from rich.console import Console, Group
 from rich.text import Text
 
+from plextui.artwork import KittyImage
 from plextui.app import (
     alphabet_group_label,
     alphabet_jump_index,
@@ -19,6 +20,7 @@ from plextui.app import (
     MediaGrid,
     MediaRow,
     PlexTuiApp,
+    card_artwork_fetch_size,
     card_artwork_pixel_size,
     context_hint,
     detect_mpv,
@@ -686,6 +688,16 @@ def test_card_artwork_pixel_size_tracks_terminal_render_size():
     assert card_artwork_pixel_size(AppConfig("http://plex", "token", "client", grid_density="large")) == (24, 24)
 
 
+def test_card_artwork_fetch_size_uses_higher_resolution_for_kitty(monkeypatch):
+    monkeypatch.setenv("KITTY_WINDOW_ID", "1")
+
+    block = AppConfig("http://plex", "token", "client", grid_density="comfortable")
+    kitty = AppConfig("http://plex", "token", "client", artwork_renderer="kitty", grid_density="comfortable")
+
+    assert card_artwork_fetch_size(block) == (18, 18)
+    assert card_artwork_fetch_size(kitty) == (216, 216)
+
+
 def test_render_card_artwork_uses_per_line_renderables():
     image = Image.new("RGB", (2, 4), "#ff0000")
     buffer = BytesIO()
@@ -697,6 +709,22 @@ def test_render_card_artwork_uses_per_line_renderables():
     assert all(isinstance(line, Text) for line in rendered.renderables)
 
 
+def test_render_card_artwork_uses_kitty_placeholders_when_enabled(monkeypatch):
+    monkeypatch.setenv("KITTY_WINDOW_ID", "1")
+    monkeypatch.setattr("plextui.artwork.emit_kitty_graphics_commands", lambda commands: None)
+    image = Image.new("RGB", (2, 4), "#ff0000")
+    buffer = BytesIO()
+    image.save(buffer, format="PNG")
+
+    rendered = render_card_artwork(
+        buffer.getvalue(),
+        AppConfig("http://plex", "token", "client", artwork_renderer="kitty", grid_density="compact"),
+    )
+
+    assert isinstance(rendered, KittyImage)
+    assert rendered.commands
+
+
 def test_render_subtitle_none_playback_status():
     config = AppConfig(
         base_url="http://plex",
@@ -830,6 +858,29 @@ def test_render_help_groups_key_bindings():
     assert "?: show help" in rendered
 
 
+def test_footer_shows_core_bindings_and_help_keeps_full_reference():
+    shown = {binding.action for binding in PlexTuiApp.BINDINGS if binding.show}
+    hidden = {binding.action for binding in PlexTuiApp.BINDINGS if not binding.show}
+    rendered = render_help()
+
+    assert shown == {
+        "quit",
+        "focus_search",
+        "focus_global_search",
+        "show_help",
+        "toggle_media_view",
+        "show_settings",
+        "back_or_clear",
+        "play_selected",
+        "resume_selected",
+    }
+    assert "audio_picker" in hidden
+    assert "subtitle_picker" in hidden
+    assert "a: choose and save audio preference" in rendered
+    assert "s: choose and save subtitle preference" in rendered
+    assert "ctrl+r: reconnect / reload libraries" in rendered
+
+
 def test_performance_log_requires_perf_env(monkeypatch):
     messages = []
     monkeypatch.delenv("PLEX_TUI_PERF_LOG", raising=False)

{plex_tui-0.3.41 → plex_tui-0.4.0}/tests/test_app_navigation.py

@@ -13,6 +13,7 @@ from plextui.app import (
     LibraryMenuRow,
     LoadMoreRow,
     PlexTuiApp,
+    artwork_fetch_pixel_size,
     card_artwork_pixel_size,
     grid_artwork_cache_key,
     grid_page_key,
@@ -293,6 +294,41 @@ def test_detail_artwork_fetches_resized_detail_and_card_artwork(monkeypatch):
     assert app.rendered_grid_artwork_cache[grid_artwork_cache_key(full_item, app.config)] == "card-art"
 
 
+def test_detail_artwork_fetches_higher_resolution_for_kitty(monkeypatch):
+    monkeypatch.setenv("KITTY_WINDOW_ID", "1")
+    app = PlexTuiApp()
+    app.config = AppConfig("http://plex", "token", "client-id", artwork_renderer="kitty", media_view="grid")
+    app.detail_refresh_token = 1
+    app.rendered_grid_artwork_cache = {}
+    full_item = MediaItem("Movie", "", "movie", "1", True, Raw(), artwork_path="/thumb")
+    details = SimpleNamespace(artwork_path="/thumb")
+    requested_sizes = []
+
+    def capture_fetch(raw, path, config, width=None, height=None):
+        requested_sizes.append((width, height))
+        return b"image"
+
+    monkeypatch.setattr(app_module, "fetch_artwork", capture_fetch)
+    monkeypatch.setattr(app_module, "render_protocol_artwork", lambda *args, **kwargs: "detail-art")
+    monkeypatch.setattr(app_module, "render_card_artwork", lambda *args, **kwargs: "card-art")
+    app.call_from_thread = lambda callback, *args: None
+
+    PlexTuiApp.fetch_media_detail_artwork.__wrapped__(
+        app,
+        full_item,
+        details,
+        token=1,
+        detail_size=(30, 20),
+        include_card_artwork=True,
+    )
+
+    assert requested_sizes == [
+        artwork_fetch_pixel_size(app.config, 30, 20),
+        artwork_fetch_pixel_size(app.config, 18, 9),
+    ]
+    assert app.rendered_grid_artwork_cache[grid_artwork_cache_key(full_item, app.config)] == "card-art"
+
+
 def test_detail_artwork_reuses_rendered_grid_card_cache(monkeypatch):
     app = PlexTuiApp()
     app.config = AppConfig("http://plex", "token", "client-id", media_view="grid")

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

@@ -7,15 +7,19 @@ from PIL import Image
 
 from plextui import artwork
 from plextui.artwork import (
+    KITTY_PLACEHOLDER,
+    KittyImage,
     add_token,
     artwork_url,
     cached_artwork_path,
     kitty_graphics_commands,
+    kitty_placeholder_lines,
     protocol_renderer_status,
     prune_artwork_cache,
     render_kitty_artwork,
     render_artwork,
     render_protocol_artwork,
+    write_all,
 )
 from plextui.config import AppConfig
 
@@ -76,7 +80,9 @@ def test_render_artwork_returns_halfcell_text():
     assert rendered.spans
 
 
-def test_render_protocol_artwork_falls_back_without_explicit_native_opt_in():
+def test_render_protocol_artwork_falls_back_without_explicit_native_opt_in(monkeypatch):
+    monkeypatch.delenv("KITTY_WINDOW_ID", raising=False)
+    monkeypatch.delenv("KITTY_PID", raising=False)
     image = Image.new("RGB", (2, 4), "#00ff00")
     buffer = BytesIO()
     image.save(buffer, format="PNG")
@@ -86,40 +92,50 @@ def test_render_protocol_artwork_falls_back_without_explicit_native_opt_in():
     assert rendered is None
 
 
-def test_render_protocol_artwork_falls_back_even_when_native_opt_in_is_enabled(monkeypatch):
+def test_render_protocol_artwork_uses_unicode_placeholders_when_kitty_is_detected(monkeypatch):
     monkeypatch.setenv("KITTY_WINDOW_ID", "1")
+    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 protocol_renderer_status("kitty") == "Block fallback; native Kitty images are disabled inside Textual"
+    assert isinstance(rendered, KittyImage)
+    assert rendered.commands[0].startswith("\033_Ga=T,f=100,q=2,i=")
+    assert ",U=1,c=2,r=2;" in rendered.commands[0]
+    assert rendered.plain.count(KITTY_PLACEHOLDER) == 4
+    assert transmitted == list(rendered.commands)
+    assert protocol_renderer_status("kitty") == "Kitty native images via Unicode placeholders"
 
 
-def test_render_kitty_artwork_builds_protocol_bytes():
+def test_render_kitty_artwork_builds_virtual_placement_and_placeholder_text():
     image = Image.new("RGB", (2, 4), "#00ff00")
     buffer = BytesIO()
     image.save(buffer, format="PNG")
 
     rendered = render_kitty_artwork(buffer.getvalue(), width=2, max_height=2)
 
-    assert "\033_Ga=T,f=100,q=2;" in rendered.plain
-    assert rendered.plain.endswith("\033\\")
+    assert isinstance(rendered, KittyImage)
+    assert rendered.commands[0].startswith("\033_Ga=T,f=100,q=2,i=")
+    assert rendered.commands[0].endswith("\033\\")
+    assert rendered.plain.count(KITTY_PLACEHOLDER) == 4
+    assert len(rendered.lines) == 2
 
 
 def test_kitty_graphics_commands_chunks_large_payload(monkeypatch):
     monkeypatch.setattr(artwork, "KITTY_PAYLOAD_CHUNK_SIZE", 8)
 
-    commands = kitty_graphics_commands("a" * 20)
+    commands = kitty_graphics_commands("a" * 20, image_id=42, columns=2, rows=2)
 
-    assert commands[0].startswith("\033_Ga=T,f=100,q=2,m=1;")
+    assert commands[0].startswith("\033_Ga=T,f=100,q=2,i=42,U=1,c=2,r=2,m=1;")
     assert commands[-1].startswith("\033_Gm=0;")
 
 
 def test_auto_protocol_renderer_requires_kitty_terminal(monkeypatch):
     monkeypatch.delenv("KITTY_WINDOW_ID", raising=False)
+    monkeypatch.delenv("KITTY_PID", raising=False)
     monkeypatch.setenv("TERM", "xterm-256color")
     image = Image.new("RGB", (2, 4), "#00ff00")
     buffer = BytesIO()
@@ -128,11 +144,38 @@ 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 fallback; native Kitty images are disabled inside Textual"
+    assert protocol_renderer_status("auto") == "Block art; Kitty terminal not detected"
+
+
+def test_protocol_renderer_status_explains_textual_fallback(monkeypatch):
+    monkeypatch.delenv("KITTY_WINDOW_ID", raising=False)
+    monkeypatch.delenv("KITTY_PID", raising=False)
+
+    assert protocol_renderer_status("kitty") == "Block fallback; Kitty terminal not detected"
+
+
+def test_kitty_placeholder_lines_encode_row_and_column_cells():
+    lines = kitty_placeholder_lines(42, columns=2, rows=2)
+
+    assert lines[0].startswith(f"{KITTY_PLACEHOLDER}\u0305\u0305")
+    assert lines[0].endswith(f"{KITTY_PLACEHOLDER}\u0305\u030d")
+    assert lines[1].startswith(f"{KITTY_PLACEHOLDER}\u030d\u0305")
+
+
+def test_write_all_retries_short_terminal_writes(monkeypatch):
+    chunks = []
+
+    def short_write(fd, payload):
+        del fd
+        chunk = bytes(payload[:3])
+        chunks.append(chunk)
+        return len(chunk)
+
+    monkeypatch.setattr(artwork.os, "write", short_write)
 
+    write_all(1, b"abcdefgh")
 
-def test_protocol_renderer_status_explains_textual_fallback():
-    assert protocol_renderer_status("kitty") == "Block fallback; native Kitty images are disabled inside Textual"
+    assert b"".join(chunks) == b"abcdefgh"
 
 
 def test_prune_artwork_cache_removes_oldest_files(tmp_path, monkeypatch):

plex_tui-0.3.41/src/plextui/artwork.py

@@ -1,198 +0,0 @@
-from __future__ import annotations
-
-import base64
-import hashlib
-from io import BytesIO
-from pathlib import Path
-from typing import Any
-from urllib.parse import urlencode, urlsplit, urlunsplit
-from urllib.request import Request, urlopen
-
-from PIL import Image, ImageOps
-from rich.text import Text
-
-from .config import AppConfig, cache_path
-
-
-MAX_IMAGE_BYTES = 12 * 1024 * 1024
-ARTWORK_CACHE_LIMIT_BYTES = 100 * 1024 * 1024
-KITTY_PAYLOAD_CHUNK_SIZE = 4096
-
-
-def fetch_artwork(raw: Any, path: str, config: AppConfig, width: int | None = None, height: int | None = None) -> bytes:
-    cached = cached_artwork_path(path, config, width, height)
-    if cached.exists():
-        return cached.read_bytes()
-
-    url = artwork_url(raw, path, config, width, height)
-    request = Request(url, headers={"User-Agent": "plex-tui"})
-    with urlopen(request, timeout=10) as response:
-        status = getattr(response, "status", 200)
-        if status != 200:
-            raise OSError(f"artwork fetch failed: HTTP {status}")
-        data = response.read(MAX_IMAGE_BYTES + 1)
-    if len(data) > MAX_IMAGE_BYTES:
-        raise OSError("artwork image is too large")
-
-    cached.parent.mkdir(parents=True, exist_ok=True)
-    cached.write_bytes(data)
-    prune_artwork_cache()
-    return data
-
-
-def artwork_url(raw: Any, path: str, config: AppConfig, width: int | None = None, height: int | None = None) -> str:
-    if width is not None and height is not None:
-        return transcode_artwork_url(path, config, width, height)
-
-    server = getattr(raw, "_server", None)
-    if server is not None and hasattr(server, "url"):
-        try:
-            return str(server.url(path, includeToken=True))
-        except Exception:
-            pass
-
-    if path.startswith("http://") or path.startswith("https://"):
-        url = path
-    else:
-        url = f"{config.base_url.rstrip('/')}/{path.lstrip('/')}"
-    return add_token(url, config.token)
-
-
-def transcode_artwork_url(path: str, config: AppConfig, width: int, height: int) -> str:
-    base_url = config.base_url.rstrip("/")
-    query = urlencode({
-        "width": max(1, width),
-        "height": max(1, height),
-        "minSize": 1,
-        "upscale": 1,
-        "url": path,
-    })
-    return add_token(f"{base_url}/photo/:/transcode?{query}", config.token)
-
-
-def add_token(url: str, token: str) -> str:
-    if not token:
-        return url
-    parts = urlsplit(url)
-    query = parts.query
-    separator = "&" if query else ""
-    query = f"{query}{separator}{urlencode({'X-Plex-Token': token})}"
-    return urlunsplit((parts.scheme, parts.netloc, parts.path, query, parts.fragment))
-
-
-def cached_artwork_path(path: str, config: AppConfig, width: int | None = None, height: int | None = None) -> Path:
-    source = f"{config.base_url}\0{path}"
-    if width is not None or height is not None:
-        source = f"{source}\0{width or ''}x{height or ''}"
-    key = hashlib.sha256(source.encode("utf-8")).hexdigest()
-    return cache_path() / "artwork" / f"{key}.img"
-
-
-def artwork_is_cached(path: str, config: AppConfig, width: int | None = None, height: int | None = None) -> bool:
-    return cached_artwork_path(path, config, width, height).exists()
-
-
-def prune_artwork_cache(limit_bytes: int = ARTWORK_CACHE_LIMIT_BYTES) -> None:
-    directory = cache_path() / "artwork"
-    if not directory.exists():
-        return
-    files = []
-    total = 0
-    try:
-        for path in directory.iterdir():
-            if not path.is_file():
-                continue
-            stat = path.stat()
-            files.append((stat.st_mtime, stat.st_size, path))
-            total += stat.st_size
-    except OSError:
-        return
-    if total <= limit_bytes:
-        return
-    for _, size, path in sorted(files):
-        try:
-            path.unlink()
-        except OSError:
-            continue
-        total -= size
-        if total <= limit_bytes:
-            break
-
-
-def render_artwork(data: bytes, width: int = 28, max_height: int = 20) -> Text:
-    image = load_image(data)
-    image = resize_for_cells(image, width, max_height)
-
-    text = Text()
-    pixels = image.load()
-    for y in range(0, image.height, 2):
-        for x in range(image.width):
-            top = pixels[x, y]
-            bottom = pixels[x, y + 1] if y + 1 < image.height else top
-            text.append("▀", style=f"{rgb(top)} on {rgb(bottom)}")
-        if y + 2 < image.height:
-            text.append("\n")
-    return text
-
-
-def render_protocol_artwork(data: bytes, renderer: str, width: int = 28, max_height: int = 20) -> object | None:
-    return None
-
-
-def resolve_protocol_renderer(renderer: str) -> str:
-    return "block"
-
-
-def protocol_renderer_status(renderer: str) -> str:
-    if renderer in {"auto", "kitty"}:
-        return "Block fallback; native Kitty images are disabled inside Textual"
-    return "Block art"
-
-
-def render_kitty_artwork(data: bytes, width: int = 28, max_height: int = 20) -> Text:
-    image = load_image(data)
-    image = resize_for_cells(image, width, max_height)
-    buffer = BytesIO()
-    image.save(buffer, format="PNG")
-    payload = base64.b64encode(buffer.getvalue()).decode("ascii")
-    return Text("".join(kitty_graphics_commands(payload)))
-
-
-def kitty_graphics_commands(payload: str) -> list[str]:
-    chunks = [
-        payload[index : index + KITTY_PAYLOAD_CHUNK_SIZE]
-        for index in range(0, len(payload), KITTY_PAYLOAD_CHUNK_SIZE)
-    ]
-    if not chunks:
-        return ["\033_Ga=T,f=100,q=2;\033\\"]
-    if len(chunks) == 1:
-        return [f"\033_Ga=T,f=100,q=2;{chunks[0]}\033\\"]
-
-    commands = []
-    for index, chunk in enumerate(chunks):
-        if index == 0:
-            prefix = "a=T,f=100,q=2,m=1"
-        elif index == len(chunks) - 1:
-            prefix = "m=0"
-        else:
-            prefix = "m=1"
-        commands.append(f"\033_G{prefix};{chunk}\033\\")
-    return commands
-
-def load_image(data: bytes) -> Image.Image:
-    return ImageOps.exif_transpose(Image.open(BytesIO(data))).convert("RGB")
-
-
-def resize_for_cells(image: Image.Image, width: int, max_height: int) -> Image.Image:
-    source_width, source_height = image.size
-    if not source_width or not source_height:
-        return Image.new("RGB", (1, 2), "#000000")
-
-    width = max(1, width)
-    max_height = max(1, max_height)
-    pixel_height = min(max_height * 2, max(2, round(source_height / source_width * width * 2)))
-    return ImageOps.contain(image, (width, pixel_height), Image.Resampling.LANCZOS)
-
-
-def rgb(color: tuple[int, int, int]) -> str:
-    return f"#{color[0]:02x}{color[1]:02x}{color[2]:02x}"