refrain 0.2.2__tar.gz → 0.2.3__tar.gz

{refrain-0.2.2 → refrain-0.2.3}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,7 +13,7 @@ body:
     attributes:
       label: Refrain version
       description: Run `refrain --version` or check the bottom-right of the settings window.
-      placeholder: "0.1.4"
+      placeholder: "0.2.3"
     validations:
       required: true
 

{refrain-0.2.2 → refrain-0.2.3}/.gitignore

@@ -39,6 +39,7 @@ env/
 # Local config / runtime
 *.log
 .refrain.local.toml
+*.local.md
 
 # Build artifacts (Flatpak / packaging)
 .flatpak-builder/

{refrain-0.2.2 → refrain-0.2.3}/CHANGELOG.md

@@ -7,6 +7,122 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-05-07
+
+A reliability + portability pass driven by hands-on testing across
+Ubuntu 25.04, CentOS Stream 10, and the existing CachyOS daily driver.
+No breaking changes — same config, same UI, same Python floor; the
+release just makes Refrain behave correctly on more distros and tightens
+a handful of long-standing rough edges.
+
+### Added
+
+- **Sandboxed Discord IPC bridge** — Snap and Flatpak Discord builds
+  publish their `discord-ipc-N` socket inside the sandbox tree instead
+  of `$XDG_RUNTIME_DIR`, so pypresence's stock discovery never finds it.
+  `_bridge_sandboxed_ipc_socket` probes the three known sandbox paths
+  (Flatpak instance dir, Flatpak config-dir layout, Snap path) and
+  symlinks the first hit into `$XDG_RUNTIME_DIR` before each connect
+  attempt. The welcome-dialog probe walks the same paths so first-run
+  diagnostics turn green on those installs.
+- **Cancel button in the update dialog** — `_apply_appimage` now
+  reads in 64 KiB chunks and polls a cancellation callback between
+  blocks. The dialog repurposes its "Later" button as "Cancel" while a
+  download is running, treats window-close as cancel, and removes the
+  partial `.AppImage.new` on abort. `UpdateResult.cancelled` lets the
+  dialog suppress the failure popup for user-initiated aborts.
+- **Orphan-download self-heal** — `cleanup_orphan_downloads` runs once
+  at startup so a `*.AppImage.new` left behind by a SIGKILL or power
+  loss mid-download doesn't sit next to the binary forever.
+- **Browser hints expanded** — Floorp, Waterfox, Mullvad Browser, Tor
+  Browser, and ungoogled-chromium are now in `DEFAULT_BROWSER_HINTS`
+  and surface as Settings checkboxes. Existing configs keep their
+  saved list (no auto-migration); the new entries appear unticked
+  until the user toggles them.
+- **iTunes-catalog duration as MPRIS override** — when MPRIS reports
+  an obviously-wrong `mpris:length` (Apple Music's preview-clip 14 s,
+  the playlist-total instead of the track length, or a stale value
+  carried over from the previous track), `pick_effective_duration_ms`
+  prefers the iTunes value if the two disagree by more than 15 % or
+  if MPRIS sits in the preview-clip band on a song iTunes considers
+  full-length. 8 new unit tests in `test_timing.py`. Discord no
+  longer briefly flips a 2:11 song's total to 0:14 / 7:21 mid-track.
+- **`docs/test-matrix.md`** — eight Tier-1 distros that together
+  cover ≈ 95 % of the realistic user base, plus Tier-2 spot-checks,
+  Tier-3 desktop / compositor combinations, and a six-step smoke
+  check ("tray + theme parity", "settings round-trip", "MPRIS to
+  Discord", "Bluetooth", "update-dialog cleanup", "restart cycle")
+  per row.
+
+### Changed
+
+- **Qt style plugin path augmentation also walks Debian / Ubuntu and
+  Fedora / RHEL / openSUSE layouts** — the v0.2.2 fix only checked
+  `/usr/lib/qt6/plugins` (Arch). pip / pipx installs on those distros
+  now also pick up the system Breeze plugin instead of falling back
+  to Fusion. Detection picks the first existing path among
+  `/usr/lib/<arch-triple>/qt6/plugins`, `/usr/lib64/qt6/plugins`,
+  `/usr/lib/qt6/plugins`.
+- **"No system tray" error** rewritten to cover GNOME, MATE, XFCE,
+  Hyprland / Sway / i3 / river, plus a "should work, try logging
+  out" hint for Plasma / Cinnamon / LXQt / Budgie. Previously the
+  fix advice was GNOME-AppIndicator-only, leaving everyone else to
+  guess.
+- **`refrain --install-desktop`** rewrites the installed
+  `Exec=` line to point at the actual launcher path of the running
+  install. Previously the bundled `Exec=refrain` only worked when
+  `refrain` was on `$PATH` (distro packages, pipx); AppImage and
+  source-checkout users got a broken menu entry. Resolution order
+  matches the autostart logic — extracted into the new
+  `autostart.resolve_exec_line(extra_args)` helper.
+- **MPRIS source duration handling decouples drift-resync from the
+  payload's preview-clip flag** — the drift-skip still keys off the
+  raw MPRIS-reported duration (because the position-field looping is
+  a property of MPRIS' preview-clip mode), but the Discord activity
+  payload's start/end fields key off the *effective* duration so a
+  brief MPRIS preview-clip glitch on a full-length song doesn't kill
+  the progress bar.
+- **PyGObject "not installed" warning fires once per startup**
+  instead of twice (eager init from `app.py` plus lazy fallback in
+  `MPRISServer.start` both used to log). The install hint also lists
+  the Fedora / RHEL / openSUSE package name (`python3-gobject`)
+  alongside the Arch and Debian ones.
+
+### Fixed
+
+- **Settings / Log / Update windows now carry the Refrain icon
+  explicitly** — on GNOME Wayland the title-based heuristic was
+  matching "Settings" against `org.gnome.Settings` and rendering the
+  gnome-control-center gear icon in the dock. The WelcomeDialog
+  already set its own icon; the other three top-level windows did
+  not.
+- **Bluetooth fast-fail when `org.bluez` is not present** — every
+  poll cycle on a VM / minimal install previously triggered a
+  `service_start_timeout=25000ms` D-Bus activation timeout, blocking
+  the worker thread for the full 25 s. `NameHasOwner` returns
+  instantly without triggering activation; the three entry points
+  (`read`, `_call_method`, `list_paired_devices`) now short-circuit
+  when the owner check returns False.
+- **Logging gaps closed in six places** — `setup_logging` runs
+  before `Config.load` so the "created default config" /
+  "config unreadable" messages reach the file log; toggling the log
+  level in Settings now applies to the running root logger via
+  `_apply_log_level` on `settings.applied`; the "no system tray"
+  early-exit gets a `log.error()`; `os.execvp`-based restarts call
+  `logging.shutdown()` first so the file handler's last buffered
+  line isn't lost; `Config.load` exception path adds `exc_info=True`;
+  `setup_logging` degrades gracefully when the XDG state dir or log
+  file can't be opened (console handler always attaches first).
+- **Catch-all exception branches in `DiscordRPC._ensure_connected`,
+  `MPRISSource._call_method_on`, and `BluetoothSource._call_method`**
+  now use `log.exception()` so the traceback lands in `refrain.log`
+  for unexpected errors. Previously they only logged `str(exc)`,
+  losing the stack exactly when it would matter most.
+- **Qt-internal log records routed through `refrain.qt`** instead
+  of the bare `qt` logger, so they parent under the project
+  namespace and show up alongside everything else when the user
+  filters by name.
+
 ## [0.2.2] - 2026-05-06
 
 Two roadmap features pulled forward from v0.3 plus a substantial batch
@@ -568,7 +684,14 @@ with a proper, installable Linux app.
   pip-audit, trufflehog, release), Dependabot, issue + PR templates,
   `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`.
 
-[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/Rockykln/refrain/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/Rockykln/refrain/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/Rockykln/refrain/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Rockykln/refrain/compare/v0.1.5...v0.2.0
+[0.1.5]: https://github.com/Rockykln/refrain/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/Rockykln/refrain/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/Rockykln/refrain/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/Rockykln/refrain/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/Rockykln/refrain/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Rockykln/refrain/releases/tag/v0.1.0

{refrain-0.2.2 → refrain-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refrain
-Version: 0.2.2
+Version: 0.2.3
 Summary: Discord Rich Presence for Apple Music on Linux
 Project-URL: Homepage, https://github.com/Rockykln/refrain
 Project-URL: Repository, https://github.com/Rockykln/refrain
@@ -134,9 +134,10 @@ and `~/.local/share/icons/`. To undo: `refrain --uninstall-desktop`.
 
 ### Tested on
 
-- KDE Plasma 6 (Wayland) — primary target
-- KDE Plasma 6 (X11)
-- GNOME (with the [AppIndicator and KStatusNotifierItem](https://extensions.gnome.org/extension/615/appindicator-support/) extension)
+See [`docs/test-matrix.md`](docs/test-matrix.md) for the full Tier-1 / Tier-2 list, the per-row smoke checks, and which distros are explicitly out-of-scope (Python or glibc floor too low).
+
+- **Tier 1 (must pass every release):** CachyOS, Arch Linux, Fedora 42, Ubuntu 24.04 LTS, Debian 13, openSUSE Tumbleweed, Linux Mint 22, Manjaro Stable.
+- **Desktops:** KDE Plasma 6 (Wayland is the primary target, X11 also covered), GNOME with the [AppIndicator and KStatusNotifierItem](https://extensions.gnome.org/extension/615/appindicator-support/) extension, XFCE / Cinnamon / LXQt / Budgie via their native or AppIndicator-bridged tray, MATE with `mate-applet-statusnotifier`, tiling WMs (Hyprland / Sway / i3 / river) via a SNI-capable status bar.
 
 ## First-time setup
 

{refrain-0.2.2 → refrain-0.2.3}/README.md

@@ -100,9 +100,10 @@ and `~/.local/share/icons/`. To undo: `refrain --uninstall-desktop`.
 
 ### Tested on
 
-- KDE Plasma 6 (Wayland) — primary target
-- KDE Plasma 6 (X11)
-- GNOME (with the [AppIndicator and KStatusNotifierItem](https://extensions.gnome.org/extension/615/appindicator-support/) extension)
+See [`docs/test-matrix.md`](docs/test-matrix.md) for the full Tier-1 / Tier-2 list, the per-row smoke checks, and which distros are explicitly out-of-scope (Python or glibc floor too low).
+
+- **Tier 1 (must pass every release):** CachyOS, Arch Linux, Fedora 42, Ubuntu 24.04 LTS, Debian 13, openSUSE Tumbleweed, Linux Mint 22, Manjaro Stable.
+- **Desktops:** KDE Plasma 6 (Wayland is the primary target, X11 also covered), GNOME with the [AppIndicator and KStatusNotifierItem](https://extensions.gnome.org/extension/615/appindicator-support/) extension, XFCE / Cinnamon / LXQt / Budgie via their native or AppIndicator-bridged tray, MATE with `mate-applet-statusnotifier`, tiling WMs (Hyprland / Sway / i3 / river) via a SNI-capable status bar.
 
 ## First-time setup
 

{refrain-0.2.2 → refrain-0.2.3}/ROADMAP.md

@@ -169,6 +169,56 @@ What's done, what's next, what's deliberately not in scope.
   in the wheel**, **MPRIS dispatch logging at INFO** so
   Next/Previous routing is visible in the live log.
 
+## Done — v0.2.3
+
+- **Distro-portability sweep** driven by hands-on testing.
+  - Qt style plugin path augmentation extended to Debian / Ubuntu
+    (`/usr/lib/<arch-triple>/qt6/plugins`) and Fedora / RHEL / openSUSE
+    (`/usr/lib64/qt6/plugins`); v0.2.2 only handled the Arch layout.
+  - Snap and Flatpak Discord builds now reachable out of the box —
+    `_bridge_sandboxed_ipc_socket` symlinks the sandboxed
+    `discord-ipc-N` into `$XDG_RUNTIME_DIR` before each pypresence
+    connect attempt.
+  - Bluetooth fast-fail via `NameHasOwner('org.bluez')` so VMs and
+    minimal installs without bluez no longer block the daemon's
+    poll cycle for 25 s waiting on D-Bus service activation.
+  - "No system tray" error covers GNOME, MATE, XFCE, and the
+    tiling-WM crowd (Hyprland / Sway / i3 / river); was
+    GNOME-AppIndicator-only.
+  - `--install-desktop` rewrites `Exec=` in the installed `.desktop`
+    to match the running install (AppImage path / venv shim / system
+    binary), so AppImage and source-checkout users get a working
+    menu entry.
+  - Browser hints expanded to cover Floorp, Waterfox, Mullvad
+    Browser, Tor Browser, ungoogled-chromium.
+- **iTunes-catalog duration as MPRIS override** —
+  `pick_effective_duration_ms` chooses iTunes when MPRIS and iTunes
+  disagree by more than 15 % or when MPRIS sits in the preview-clip
+  band on a song iTunes considers full-length. Apple Music's MPRIS
+  surface no longer makes Discord briefly flip a 2:11 song's total
+  to 0:14 / 7:21 mid-track.
+- **Update-dialog Cancel + orphan-download self-heal** — `Cancel`
+  button + window-close handler abort an in-flight AppImage
+  download cleanly and remove the partial `.new`. A separate
+  `cleanup_orphan_downloads` runs at startup so a SIGKILL or power
+  loss mid-download doesn't leave a stale `*.AppImage.new` next to
+  the binary forever.
+- **Per-window icons** on Settings / Log / Update dialogs so GNOME
+  Shell's title-based heuristic on Wayland doesn't render them with
+  the gnome-control-center gear icon in the dock.
+- **Logging audit** closed six gaps: `setup_logging` runs before
+  `Config.load` so config-load messages reach the file log; the
+  log-level toggle in Settings applies live; `setup_logging` degrades
+  gracefully when the XDG state dir is unwritable; `os.execvp`-based
+  restarts flush log handlers first; catch-all exception branches in
+  `DiscordRPC._ensure_connected`, `MPRISSource._call_method_on` and
+  `BluetoothSource._call_method` switched to `log.exception()` so
+  tracebacks land in `refrain.log`.
+- **`docs/test-matrix.md`** — eight Tier-1 distros, Tier-2 spot-check
+  list, Tier-3 desktop / compositor sweep, six-step smoke checks,
+  out-of-scope reasons for the floor of unsupported distros (RHEL 9
+  / Rocky 9 / Alma 9 / Debian 11 / Ubuntu 22.04 / Alpine).
+
 ## Up next — v0.3
 
 - **Polishing the wrapped i18n surface** — wrap the remaining

refrain-0.2.3/docs/test-matrix.md

@@ -0,0 +1,169 @@
+# Test matrix
+
+The set of distros + desktop combinations Refrain is expected to work on,
+and a six-step smoke test to run on each before declaring a release good
+to ship. Tick boxes as you verify; leave a date + Refrain version in the
+"Last verified" column.
+
+## How to use this document
+
+For each row in the matrix:
+
+1. Run through the six checks under [Smoke checks](#smoke-checks).
+2. If everything passes, tick the row's checkbox and write the date +
+   Refrain version into "Last verified".
+3. If something fails, file an issue and leave the row unticked. Note
+   the failing check in "Notes".
+
+A row failing one minor optional check (e.g. notifications missing
+because `notify-send` isn't installed) is fine — that's documented
+graceful-degradation, not a regression.
+
+## Tier 1 — primary support, must pass every release
+
+These are the eight systems that together cover ≈ 95 % of the realistic
+user base. CachyOS / KDE Plasma 6 / Wayland is the maintainer's daily
+driver and should be tested on every commit; the rest before each tag.
+
+| ✓ | Distro | Desktop | Display server | Channel | Last verified | Notes |
+|---|---|---|---|---|---|---|
+| [ ] | **CachyOS** (rolling) | KDE Plasma 6 | Wayland | AUR `refrain` | | maintainer daily |
+| [ ] | **Arch Linux** (rolling) | KDE Plasma 6 | X11 | AUR `refrain` | | alternate display server |
+| [ ] | **Fedora 42 Workstation** | GNOME 47 | Wayland | AppImage + PyPI | | RPM world + GNOME tray ext. |
+| [ ] | **Ubuntu 24.04 LTS** | GNOME 46 | Wayland | AppImage | | LTS, glibc floor |
+| ❌ | **Ubuntu 25.04** | GNOME 48 | Wayland | PyPI | 2026-05-07 / v0.2.2 | Tested + **failed**. Settings window came up with the gnome-control-center icon (Wayland app-id matching heuristic; fixed in `1e759ba` by setting per-window icon explicitly). Snap-sandboxed Firefox + Chrome both refused to publish MPRIS so Refrain saw no players — distro-external, workaround is a deb-channel browser (Brave / Mozilla apt repo). 25 s `org.bluez` activation timeout per poll when bluez isn't present (fast-fail via `NameHasOwner` added in follow-up). Re-test with v0.2.3+ once those fixes ship. |
+| [ ] | **Debian 13** (Trixie) | KDE Plasma 6 | Wayland | AppImage | | Plasma outside Arch |
+| [ ] | **openSUSE Tumbleweed** | KDE Plasma 6 | Wayland | PyPI in venv | | rolling non-Arch |
+| [ ] | **Linux Mint 22** | Cinnamon 6 | X11 | AppImage | | Cinnamon tray, X11 |
+| [ ] | **Manjaro** Stable | KDE Plasma 6 | Wayland | AUR `refrain` | | delayed Arch mirror |
+
+## Tier 2 — supported, spot-check
+
+Less frequent verification — once per minor release is enough.
+
+| ✓ | Distro | Desktop | Channel | Notes |
+|---|---|---|---|---|
+| [ ] | **EndeavourOS** | KDE | AUR `refrain` | Arch derivative |
+| [ ] | **Garuda Linux** | KDE | AUR `refrain` | Arch derivative |
+| [ ] | **Pop!_OS 24.04** | GNOME (or COSMIC) | AppImage | COSMIC tray TBD |
+| [ ] | **KDE Neon** (User) | KDE Plasma 6 | PyPI / AppImage | Plasma testing target |
+| [ ] | **Ubuntu 25.04** | GNOME | PyPI in venv | Python 3.13 |
+| [ ] | **Debian 12** (Bookworm) | KDE / GNOME | AppImage | Python 3.11, Qt 5 — AppImage required |
+| [ ] | **Fedora 41 KDE Spin** | KDE Plasma 6 | Wayland | AppImage / PyPI | Fedora KDE flavour |
+| [ ] | **NixOS** unstable | KDE / GNOME | PyPI in nix-shell | flake.nix would be nice-to-have |
+
+## Tier 3 — desktop / compositor edge cases
+
+Not full distro entries — just verify the tray + tray icon rendering
+on these specifically.
+
+| ✓ | Compositor / DE | Tray status | Notes |
+|---|---|---|---|
+| [ ] | KDE Plasma 6 — Wayland | native ✓ | primary target |
+| [ ] | KDE Plasma 6 — X11 | native ✓ | |
+| [ ] | GNOME 45+ | needs [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/) | refuses start without it |
+| [ ] | XFCE 4.18+ | OK with `xfce4-statusnotifier-plugin` | |
+| [ ] | Cinnamon 6 | native ✓ | |
+| [ ] | LXQt 2 | native ✓ | |
+| [ ] | Budgie | OK via AppIndicator | |
+| [ ] | MATE | needs `mate-applet-statusnotifier` | |
+| [ ] | Hyprland / Sway / i3 | needs SNI-capable bar (waybar `tray` module, polybar) | |
+| [ ] | Pantheon (elementary) | unofficial SNI support | untested |
+| [ ] | COSMIC (Pop!_OS 24.04+) | own protocol | untested |
+
+## Out of scope (won't work)
+
+These are documented as **unsupported** — don't open issues for them.
+
+| Distro | Reason |
+|---|---|
+| Debian 11 (Bullseye) | Python 3.9 — too old |
+| Ubuntu 20.04 / 22.04 LTS | Python 3.8 / 3.10 too old; AppImage glibc floor too high for 22.04 |
+| Linux Mint 21.x | Python 3.10 — too old |
+| **CentOS Stream 10** | Tested 2026-05-07 against v0.2.2 — **failed**. AppImage in mounted mode needs `fuse` (not just `fuse-libs`) which the docs didn't surface; in `--appimage-extract-and-run` mode raises `No module named refrain` on a fresh extract. PyPI install starts but GNOME default ships no AppIndicator package out of the box — Refrain refuses to launch with "No system tray". Reachable only with manual Extension-Manager dance. Not Tier-1/2 worth. |
+| CentOS Stream 9 | glibc 2.34 < 2.35 (AppImage breaks); Python 3.9 default |
+| RHEL 9 / Rocky 9 / AlmaLinux 9 | same family as CentOS Stream 9 |
+| RHEL 8 / Rocky 8 / AlmaLinux 8 | glibc 2.28; Python 3.6 default |
+| Alpine Linux | musl libc — PySide6 wheels are glibc-only |
+| openSUSE Leap 15.5 | Python 3.6 default |
+
+## Smoke checks
+
+Run all six on every Tier 1 row, in order. Each should take under a
+minute; the whole sweep is ≈ 5 minutes per system.
+
+### 1. Tray + theme parity
+
+- Refrain icon appears in the system tray on launch.
+- Icon style matches the system theme (light glyph on dark panel,
+  dark glyph on light panel).
+- Settings window styling matches the rest of the desktop (Breeze
+  on KDE, Adwaita-via-Qt on GNOME, etc.). The pip / pipx / AppImage
+  builds should look the same as the AUR / system build because of
+  the Qt-plugin-path augmentation in `app.py`.
+
+### 2. Settings round-trip
+
+- Tray → *Settings…* opens the window.
+- Toggle any setting (e.g. *Notifications*), hit *Apply*.
+- Window closes; setting persists in `~/.config/refrain/config.toml`.
+- No console errors, no Qt crashes.
+
+### 3. MPRIS / Apple Music — Discord push
+
+- Open `https://music.apple.com` in any major Linux browser.
+- Start playing a track.
+- Within ≈ 1 s, the tray menu shows the track title + artist.
+- Within ≈ 2 s, Discord status shows "Listening to ..." with the
+  cover art.
+- **Duration check**: progress bar in Discord shows the *correct*
+  total length for the track (e.g. a 2:11 song shows 2:11, not 0:14
+  or 7:21).
+
+### 4. Bluetooth source (optional, hardware-dependent)
+
+Skip if no AVRCP-capable Bluetooth source is available. Otherwise:
+
+- Pair + connect a phone playing music via Bluetooth.
+- Tray menu shows the track within ≈ 1 s.
+- Discord status pushes the metadata.
+- Per-source `client_id_bluetooth` (if set) routes to the right
+  Discord application.
+
+### 5. Update dialog cleanup
+
+Triggered automatically when a newer version exists; or set
+`update.last_check_ts = 0` in the config and restart.
+
+- Update dialog opens with a working *Cancel* button while
+  downloading.
+- Hitting Cancel mid-download removes the `*.AppImage.new` file
+  next to the binary (only relevant for AppImage installs).
+- Closing the dialog window via the X button while downloading
+  also cancels cleanly.
+- After cancel, no orphan `.new` file is left behind.
+
+### 6. Restart cycle
+
+- Tray → *Restart Refrain*.
+- The process exits cleanly, releases the D-Bus name
+  `io.github.Rockykln.Refrain`, and re-execs itself.
+- Tray icon disappears and reappears within ≈ 2 s.
+- Discord RPC reconnects and the same track shows up again.
+- `refrain.log` has a `Re-execing for restart` line followed by a
+  fresh `Refrain ... starting` line — no duplicate D-Bus name
+  errors.
+
+## Failure-mode reference
+
+If a check fails, the most common causes:
+
+| Symptom | Likely cause |
+|---|---|
+| Refrain refuses to start with "No system tray" | Missing AppIndicator extension on GNOME, or bar with no tray on tiling WM |
+| Tray icon visible but no track shown when playing in browser | `plasma-browser-integration` not enabled in browser, or `mpris_enabled = false` |
+| Discord status never appears | No `client_id` set, or Discord IPC socket not reachable (Snap/Flatpak Discord can hide it) |
+| Cover art missing | iTunes Search has no match for that artist / title — fallback brand icon shown |
+| Settings window has no icons / wrong style on pip/pipx install | Qt plugin-path augmentation didn't fire — check log for `Augmenting Qt plugin path` |
+| Duration shows as 0:14 or some too-short value | Pre-`pick_effective_duration_ms` build, or iTunes lookup hasn't resolved yet for that track |
+| AppImage fails with `failed to exec fusermount` (RHEL family) | `fuse-libs` alone is not enough — install the `fuse` package too, or run with `--appimage-extract-and-run` |

{refrain-0.2.2 → refrain-0.2.3}/packaging/appimage/AppImageBuilder.yml

@@ -30,7 +30,7 @@ AppDir:
     id: io.github.Rockykln.Refrain
     name: Refrain
     icon: refrain
-    version: 0.2.2
+    version: 0.2.3
     exec: usr/bin/python3
     exec_args: -m refrain $@
 

refrain-0.2.3/packaging/aur/refrain/.SRCINFO

@@ -0,0 +1,19 @@
+pkgbase = refrain
+	pkgdesc = Discord Rich Presence for Apple Music on Linux
+	pkgver = 0.2.2
+	pkgrel = 1
+	url = https://github.com/Rockykln/refrain
+	arch = any
+	license = custom:Refrain
+	makedepends = python-build
+	makedepends = python-installer
+	makedepends = python-hatchling
+	makedepends = python-wheel
+	depends = python>=3.11
+	depends = python-pypresence
+	depends = python-dbus
+	depends = pyside6
+	source = refrain-0.2.2.tar.gz::https://github.com/Rockykln/refrain/archive/v0.2.2.tar.gz
+	sha256sums = db07e0783b3f44a7c54d4b8ee2ebe33f3dc577707a03bd42f5958ddae3d5ac12
+
+pkgname = refrain

{refrain-0.2.2 → refrain-0.2.3}/packaging/aur/refrain/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Rockykln <contact@rockykln.com>
 
 pkgname=refrain
-pkgver=0.2.2
+pkgver=0.2.3
 pkgrel=1
 pkgdesc="Discord Rich Presence for Apple Music on Linux"
 arch=('any')
@@ -13,6 +13,9 @@ depends=(
     'python-dbus'
     'pyside6'
 )
+optdepends=(
+    'python-gobject: enables MPRIS-server publication so Plasma media controls reach Refrain'
+)
 makedepends=(
     'python-build'
     'python-installer'
@@ -20,7 +23,10 @@ makedepends=(
     'python-wheel'
 )
 source=("$pkgname-$pkgver.tar.gz::https://github.com/Rockykln/refrain/archive/v$pkgver.tar.gz")
-sha256sums=('SKIP')  # set after release tag is pushed: updpkgsums
+# Placeholder — recompute after the GitHub release exists:
+#   curl -sLO "https://github.com/Rockykln/refrain/archive/v${pkgver}.tar.gz"
+#   sha256sum "v${pkgver}.tar.gz"
+sha256sums=('SKIP')
 
 build() {
     cd "$pkgname-$pkgver"

{refrain-0.2.2 → refrain-0.2.3}/packaging/flatpak/io.github.Rockykln.Refrain.metainfo.xml

@@ -51,6 +51,27 @@
   <content_rating type="oars-1.1" />
 
   <releases>
+    <release version="0.2.3" date="2026-05-07">
+      <description>
+        <p>
+          Reliability + portability pass. Sandbox-aware Discord IPC
+          discovery so Snap and Flatpak Discord builds are reachable
+          out of the box, Qt style plugin path augmentation extended
+          to Debian / Ubuntu / Fedora / RHEL / openSUSE layouts so
+          pip / pipx installs render in the system theme on those
+          distros (was Arch-only in 0.2.2), Bluetooth fast-fail so
+          VMs without bluez don't stall the poll cycle for 25 s, and
+          "No system tray" advice extended past the GNOME
+          AppIndicator hint to cover MATE, XFCE, and tiling
+          window managers. Plus a Cancel button on the update
+          dialog, orphan-download self-heal, per-window icons (no
+          more gnome-control-center gear icon on Wayland), an
+          iTunes-catalog duration override that fixes Discord briefly
+          flipping a 2:11 song's total to 0:14 mid-track, and a
+          six-step distro test matrix in docs/test-matrix.md.
+        </p>
+      </description>
+    </release>
     <release version="0.2.2" date="2026-05-06">
       <description>
         <p>

{refrain-0.2.2 → refrain-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "refrain"
-version = "0.2.2"
+version = "0.2.3"
 description = "Discord Rich Presence for Apple Music on Linux"
 readme = "README.md"
 requires-python = ">=3.11"

refrain-0.2.3/src/refrain/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.3"