plex-tui 0.2.0__tar.gz → 0.2.1__tar.gz

plex_tui-0.2.1/.github/workflows/aur.yml

@@ -0,0 +1,49 @@
+name: AUR Package
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - ".github/workflows/aur.yml"
+      - "packaging/aur/**"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - ".github/workflows/aur.yml"
+      - "packaging/aur/**"
+  workflow_dispatch:
+
+jobs:
+  makepkg:
+    runs-on: ubuntu-latest
+    container: archlinux:base-devel
+
+    steps:
+      - name: Install runner dependencies
+        run: |
+          pacman -Syu --noconfirm git namcap sudo
+
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Create build user
+        run: |
+          useradd --create-home --shell /bin/bash builder
+          echo "builder ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/builder
+          chown -R builder:builder "$GITHUB_WORKSPACE"
+
+      - name: Build and check package
+        working-directory: packaging/aur
+        run: |
+          sudo -u builder makepkg --clean --syncdeps --noconfirm --check
+
+      - name: Generate .SRCINFO
+        working-directory: packaging/aur
+        run: |
+          sudo -u builder makepkg --printsrcinfo > .SRCINFO.generated
+          diff -u .SRCINFO .SRCINFO.generated
+
+      - name: Run namcap
+        working-directory: packaging/aur
+        run: |
+          namcap PKGBUILD ./*.pkg.tar.*

plex_tui-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  check:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run checks
+        run: make PYTHON=python check

plex_tui-0.2.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git ref to publish, such as v0.2.0"
+        required: true
+        type: string
+  release:
+    types: ["published"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check dist/*
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

plex_tui-0.2.1/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,38 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: testpypi
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check dist/*
+
+      - name: Publish package to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

{plex_tui-0.2.0 → plex_tui-0.2.1}/.gitignore

@@ -1,4 +1,5 @@
 .venv/
+.venv*/
 __pycache__/
 *.py[cod]
 .pytest_cache/

{plex_tui-0.2.0 → plex_tui-0.2.1}/AGENTS.md

@@ -11,6 +11,9 @@ through `mpv`.
   - `player.py`: `mpv` launch, stream selection, and playback diagnostics.
   - `config.py`, `auth.py`, `artwork.py`, `models.py`: supporting modules.
 - `tests/`: pytest suite, split by app helpers/navigation and service modules.
+- `.github/workflows/`: CI plus PyPI/TestPyPI/AUR validation workflows.
+- `packaging/`: Homebrew and AUR maintenance notes; `packaging/aur/` contains
+  the source copy of `PKGBUILD` and `.SRCINFO`.
 - `README.md`, `PACKAGING.md`, `RELEASE.md`, `ROADMAP.md`: user and release docs.
 - `config.example.toml`: example user configuration.
 
@@ -59,6 +62,8 @@ make smoke
 ```
 
 For packaging or metadata changes, also run `make check-package` or `make check`.
+For AUR package changes, run the `AUR Package` workflow or validate with
+`makepkg` on Arch.
 
 ## Commit & Pull Request Guidelines
 

{plex_tui-0.2.0 → plex_tui-0.2.1}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.1 - 2026-06-11
+
+- Added GitHub Actions CI and PyPI Trusted Publishing workflow scaffolding.
+- Added a manual TestPyPI Trusted Publishing workflow.
+- Published `plex-tui` to PyPI and updated install documentation.
+- Published the Homebrew tap and updated install documentation.
+- Added Arch package validation workflow scaffolding.
+- Published the Arch AUR package and updated install documentation.
+- Added Arch AUR packaging files and Homebrew packaging notes.
+- Refreshed documentation for current install, packaging, and release workflows.
+- Added a Settings diagnostics action for recent `debug.log` output and playback error details with log context.
+- Clarified Settings rows with action-type tags and per-row detail-pane guidance.
+- Improved grid browsing smoothness by debouncing detail reloads, throttling artwork prefetch, and avoiding cached-artwork rendering during selection redraws.
+- Made grid detail reloads idle-aware so rapid selection movement no longer starts stale Plex reload workers.
+- Made grid artwork appear progressively as each card renders and added stronger focused-pane styling.
+- Added an explicit `[FOCUS]` marker to the active pane title.
+- Kept focus markers in sync when using Tab navigation and refocused the visible browser after list/grid view changes.
+- Made Tab navigation cycle explicitly through Libraries, Media, and Details panes.
+- Added a short idle debounce for list detail reloads to reduce detail-pane churn during fast row movement.
+- Increased the list detail debounce to further reduce repeated artwork loads during row navigation.
+- Split detail text refresh from detail artwork loading so artwork waits for a longer stable selection window.
+
 ## 0.2.0 - 2026-06-11
 
 - Improved README structure and expanded the post-0.1.0 roadmap.

plex_tui-0.2.1/PACKAGING.md

@@ -0,0 +1,102 @@
+# Packaging
+
+plex-tui is distributed through PyPI, a Homebrew tap, and the Arch AUR. The
+source repository remains the canonical place for versioning, release notes,
+and validation.
+
+## Supported Channels
+
+### PyPI
+
+Recommended cross-platform install:
+
+```bash
+pipx install plex-tui
+```
+
+PyPI publishing uses GitHub Actions Trusted Publishing:
+
+- Workflow: `.github/workflows/publish-pypi.yml`
+- PyPI environment: `pypi`
+- Trigger: GitHub Release publication, or manual workflow dispatch with a ref
+
+TestPyPI uses a separate manual workflow:
+
+- Workflow: `.github/workflows/publish-testpypi.yml`
+- TestPyPI environment: `testpypi`
+
+Install tests from TestPyPI need PyPI as a dependency fallback:
+
+```bash
+python -m pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  plex-tui
+```
+
+### Homebrew
+
+Tap repository:
+
+```text
+https://github.com/so1omon563/homebrew-plex-tui
+```
+
+User install:
+
+```bash
+brew tap so1omon563/plex-tui
+brew install plex-tui
+```
+
+The formula depends on `mpv` and `python@3.13`, then installs the Python app in
+a Homebrew-managed virtualenv. The first install can take several minutes
+because native Python resources such as `pillow` are built from source.
+
+Validation commands:
+
+```bash
+brew test so1omon563/plex-tui/plex-tui
+brew audit --strict --online so1omon563/plex-tui/plex-tui
+```
+
+### Arch AUR
+
+AUR package:
+
+```text
+https://aur.archlinux.org/packages/plex-tui
+```
+
+User install:
+
+```bash
+paru -S plex-tui
+```
+
+The source copy for AUR metadata lives in `packaging/aur/`. The package uses
+Arch system dependencies, including `mpv`, `python-textual`, `python-pillow`,
+`python-plexapi`, `python-platformdirs`, and `python-rich`.
+
+Validation is handled by `.github/workflows/aur.yml`, which runs inside
+`archlinux:base-devel` and checks:
+
+- `makepkg --clean --syncdeps --noconfirm --check`
+- `.SRCINFO` is in sync with `PKGBUILD`
+- `namcap PKGBUILD ./*.pkg.tar.*`
+
+## Release Maintenance
+
+For each new app release:
+
+1. Publish and validate PyPI.
+2. Update the Homebrew tap formula URL/hash and Python resources.
+3. Update `packaging/aur/PKGBUILD` and `packaging/aur/.SRCINFO`.
+4. Run packaging validation workflows.
+5. Push the AUR package repo update after the workflow passes.
+
+## Known Follow-Up
+
+- Automate Homebrew tap updates after PyPI publishing.
+- Investigate faster Homebrew installs without compromising formula quality.
+- Consider standalone artifacts only after the app behavior stabilizes.

{plex_tui-0.2.0 → plex_tui-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plex-tui
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -39,9 +39,9 @@ Description-Content-Type: text/markdown
 A standalone Python/Textual terminal UI for browsing Plex and launching playback
 through `mpv`.
 
-plex-tui is currently an early release. It supports Plex login, server
-selection, paged library browsing, search, list/grid views, stream preferences,
-terminal poster artwork, and playback progress reporting.
+plex-tui is an early release. It supports Plex login, server selection, paged
+library browsing, search, list/grid views, stream preferences, terminal poster
+artwork, and playback progress reporting.
 
 ## Screenshots
 
@@ -59,7 +59,8 @@ terminal poster artwork, and playback progress reporting.
 - `mpv` available on `PATH`
 - A Plex account/server
 
-Install `mpv` with your platform package manager:
+When installing with PyPI or from GitHub, install `mpv` with your platform
+package manager:
 
 ```bash
 # macOS
@@ -75,25 +76,52 @@ sudo dnf install mpv
 sudo pacman -S mpv
 ```
 
-## Install
+## Installation
 
-The README tracks the current `main` branch. Tagged releases are available on
-the GitHub Releases page.
-
-The recommended install path for the latest `main` branch is `pipx`:
+### PyPI
 
 ```bash
-pipx install "git+https://github.com/so1omon563/plex-tui.git"
+pipx install plex-tui
 plex-tui --smoke
 plex-tui
 ```
 
-To install the latest tagged release instead:
+This is the recommended cross-platform install path. It keeps Python
+dependencies isolated, but you still need to install `mpv` separately.
+If `pipx` is not installed, install it with your platform package manager first
+or follow the pipx installation guide.
+
+### Homebrew
+
+```bash
+brew tap so1omon563/plex-tui
+brew install plex-tui
+plex-tui --smoke
+```
+
+The Homebrew formula installs `mpv` automatically. The first install can take
+several minutes because native Python dependencies such as `pillow` are built
+from source.
+
+### Arch Linux
+
+```bash
+paru -S plex-tui
+plex-tui --smoke
+```
+
+The AUR package depends on `mpv`. Any AUR helper can be used; `paru` is only an
+example.
+
+### GitHub
 
 ```bash
-pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.2.0"
+pipx install "git+https://github.com/so1omon563/plex-tui.git"
+pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.2.1"
 ```
 
+Use this path for testing `main` before a tagged/PyPI release.
+
 Useful CLI checks:
 
 ```bash
@@ -120,6 +148,9 @@ On first run, plex-tui starts a Plex browser login and asks which server
 connection to save. If a browser cannot be opened, use the login URL shown in
 the terminal.
 
+The login flow writes a config file with the selected server URL and token. Use
+the Settings screen or `plex-tui --config-path` to find the active file.
+
 You can also configure a server manually. macOS config path:
 
 ```bash
@@ -150,6 +181,13 @@ export PLEX_TUI_TOKEN="your-plex-token"
 
 See `config.example.toml` for optional settings.
 
+## Playback
+
+Playback is launched through `mpv`; plex-tui does not embed a video player.
+While playback is active, Plex progress is updated in the background. Saved
+audio/subtitle language preferences are applied when matching streams are
+available, and the details pane shows the effective playback choices.
+
 ## Key Bindings
 
 | Key | Action |
@@ -182,7 +220,8 @@ See `config.example.toml` for optional settings.
 - Audio and subtitle pickers with saved language preferences.
 - Plex resume support and playback progress reporting.
 - Settings screen for stream preferences, artwork modes, grid density, page
-  size, auto-load threshold, media view, and `mpv` window size.
+  size, auto-load threshold, grid artwork prefetching, media view, and `mpv`
+  window size.
 
 ## Artwork
 
@@ -191,22 +230,38 @@ terminals without Kitty, iTerm2, or Sixel support. Native terminal image output
 is disabled for now because Kitty protocol rendering conflicts with Textual's
 screen renderer in practice.
 
-Grid view prefetches artwork for the visible page immediately and the next page
-after selection settles. Compact, comfortable, and large density modes adjust
-card and poster sizing. The artwork cache is bounded and stored in the app cache
-directory shown in Settings.
+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
+from `0` to `5`; use `0` to fetch only the visible page on slower systems.
+Compact, comfortable, and large density modes adjust card and poster sizing. The
+artwork cache is bounded and stored in the app cache directory shown in
+Settings.
 
 ## Diagnostics
 
 Playback diagnostics are written to `debug.log` in the app config directory.
 Tokens are redacted from logged `mpv` arguments.
 
+Useful paths:
+
+```bash
+plex-tui --config-path
+plex-tui --debug-log-path
+```
+
 Enable browsing performance timings before launch:
 
 ```bash
 PLEX_TUI_PERF_LOG=1 plex-tui
 ```
 
+Verbose grid artwork internals are quieter by default. Include them only when
+debugging poster loading:
+
+```bash
+PLEX_TUI_PERF_LOG=1 PLEX_TUI_ARTWORK_LOG=1 plex-tui
+```
+
 ## Development
 
 Common commands:

{plex_tui-0.2.0 → plex_tui-0.2.1}/README.md

@@ -3,9 +3,9 @@
 A standalone Python/Textual terminal UI for browsing Plex and launching playback
 through `mpv`.
 
-plex-tui is currently an early release. It supports Plex login, server
-selection, paged library browsing, search, list/grid views, stream preferences,
-terminal poster artwork, and playback progress reporting.
+plex-tui is an early release. It supports Plex login, server selection, paged
+library browsing, search, list/grid views, stream preferences, terminal poster
+artwork, and playback progress reporting.
 
 ## Screenshots
 
@@ -23,7 +23,8 @@ terminal poster artwork, and playback progress reporting.
 - `mpv` available on `PATH`
 - A Plex account/server
 
-Install `mpv` with your platform package manager:
+When installing with PyPI or from GitHub, install `mpv` with your platform
+package manager:
 
 ```bash
 # macOS
@@ -39,25 +40,52 @@ sudo dnf install mpv
 sudo pacman -S mpv
 ```
 
-## Install
+## Installation
 
-The README tracks the current `main` branch. Tagged releases are available on
-the GitHub Releases page.
-
-The recommended install path for the latest `main` branch is `pipx`:
+### PyPI
 
 ```bash
-pipx install "git+https://github.com/so1omon563/plex-tui.git"
+pipx install plex-tui
 plex-tui --smoke
 plex-tui
 ```
 
-To install the latest tagged release instead:
+This is the recommended cross-platform install path. It keeps Python
+dependencies isolated, but you still need to install `mpv` separately.
+If `pipx` is not installed, install it with your platform package manager first
+or follow the pipx installation guide.
+
+### Homebrew
+
+```bash
+brew tap so1omon563/plex-tui
+brew install plex-tui
+plex-tui --smoke
+```
+
+The Homebrew formula installs `mpv` automatically. The first install can take
+several minutes because native Python dependencies such as `pillow` are built
+from source.
+
+### Arch Linux
+
+```bash
+paru -S plex-tui
+plex-tui --smoke
+```
+
+The AUR package depends on `mpv`. Any AUR helper can be used; `paru` is only an
+example.
+
+### GitHub
 
 ```bash
-pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.2.0"
+pipx install "git+https://github.com/so1omon563/plex-tui.git"
+pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.2.1"
 ```
 
+Use this path for testing `main` before a tagged/PyPI release.
+
 Useful CLI checks:
 
 ```bash
@@ -84,6 +112,9 @@ On first run, plex-tui starts a Plex browser login and asks which server
 connection to save. If a browser cannot be opened, use the login URL shown in
 the terminal.
 
+The login flow writes a config file with the selected server URL and token. Use
+the Settings screen or `plex-tui --config-path` to find the active file.
+
 You can also configure a server manually. macOS config path:
 
 ```bash
@@ -114,6 +145,13 @@ export PLEX_TUI_TOKEN="your-plex-token"
 
 See `config.example.toml` for optional settings.
 
+## Playback
+
+Playback is launched through `mpv`; plex-tui does not embed a video player.
+While playback is active, Plex progress is updated in the background. Saved
+audio/subtitle language preferences are applied when matching streams are
+available, and the details pane shows the effective playback choices.
+
 ## Key Bindings
 
 | Key | Action |
@@ -146,7 +184,8 @@ See `config.example.toml` for optional settings.
 - Audio and subtitle pickers with saved language preferences.
 - Plex resume support and playback progress reporting.
 - Settings screen for stream preferences, artwork modes, grid density, page
-  size, auto-load threshold, media view, and `mpv` window size.
+  size, auto-load threshold, grid artwork prefetching, media view, and `mpv`
+  window size.
 
 ## Artwork
 
@@ -155,22 +194,38 @@ terminals without Kitty, iTerm2, or Sixel support. Native terminal image output
 is disabled for now because Kitty protocol rendering conflicts with Textual's
 screen renderer in practice.
 
-Grid view prefetches artwork for the visible page immediately and the next page
-after selection settles. Compact, comfortable, and large density modes adjust
-card and poster sizing. The artwork cache is bounded and stored in the app cache
-directory shown in Settings.
+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
+from `0` to `5`; use `0` to fetch only the visible page on slower systems.
+Compact, comfortable, and large density modes adjust card and poster sizing. The
+artwork cache is bounded and stored in the app cache directory shown in
+Settings.
 
 ## Diagnostics
 
 Playback diagnostics are written to `debug.log` in the app config directory.
 Tokens are redacted from logged `mpv` arguments.
 
+Useful paths:
+
+```bash
+plex-tui --config-path
+plex-tui --debug-log-path
+```
+
 Enable browsing performance timings before launch:
 
 ```bash
 PLEX_TUI_PERF_LOG=1 plex-tui
 ```
 
+Verbose grid artwork internals are quieter by default. Include them only when
+debugging poster loading:
+
+```bash
+PLEX_TUI_PERF_LOG=1 PLEX_TUI_ARTWORK_LOG=1 plex-tui
+```
+
 ## Development
 
 Common commands: