refrain 0.2.2__tar.gz → 0.2.4__tar.gz

{refrain-0.2.2 → refrain-0.2.4}/.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.4}/.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.4}/CHANGELOG.md

@@ -7,6 +7,250 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-05-07
+
+A polish + reliability release built on the v0.2.3 distro-portability
+work. The headline items are time-display consistency across all
+three surfaces (tray / Discord / Plasma panel), Snap/Flatpak Discord
+support out of the box, a full inline changelog in Settings, and
+~20 % more test coverage to lock the new behaviour in. No breaking
+changes — same config schema, same Python floor, same UI layout.
+
+### Added
+
+- **Inline release notes in Settings → Updates tab.** The tab
+  previously only had an auto-check toggle, last-checked label and a
+  "Check now" button — the actual release notes only showed up in
+  the popup when an update was available. The tab now carries a
+  QTextBrowser that renders the same Markdown the popup uses, plus
+  "Current version" and "Latest known" labels. `UpdateOrchestrator`
+  gained a `releaseInfoFetched(release | None)` signal that fires
+  after every check (auto or manual, success or failure) so the tab
+  refreshes its contents regardless of the result.
+- **`docs/bluetooth.md`** — first-time-setup walkthrough covering
+  bluez install per distro, pairing recipe, AVRCP verification,
+  per-source Discord profile setup, and a Troubleshooting section
+  for the common breakage modes (no AVRCP exposed, missing
+  control, multiple paired devices, empty dropdown).
+- **FAQ entries** for "Refrain isn't picking up my browser"
+  (covers the `playerctl` diagnostic, the Snap-confined-browser
+  workaround, and the Firefox `about:config` toggle), and
+  "How do I add a browser that isn't in the list".
+
+### Changed
+
+- **Tray progress + published MPRIS metadata + Discord activity
+  payload all use the iTunes-corrected duration.** v0.2.3 already
+  fixed Discord; the tray's "0:42 / 7:21 (-6:39)" ticker and the
+  `mpris:length` we publish to Plasma's panel were still using the
+  raw `mpris:length` and showed inconsistent numbers when MPRIS
+  briefly lied about a song's duration. Hoisted
+  `pick_effective_duration_ms` into `_dispatch` so all three
+  surfaces see the same value every tick. Tray position is also
+  now clamped to duration so a "2:30 / 0:14 (-0:00)" display can't
+  happen during a brief MPRIS preview-clip glitch on a longer song.
+- **`os.chmod(tmp, 0o755)` on AppImage update replaced by mode
+  preservation** — read the running AppImage's mode and mirror it,
+  with `0o700` as fallback. CodeQL's `py/overly-permissive-file`
+  warning is gone, and an AppImage that the user installed at
+  `0o700` stays `0o700` across upgrades.
+- **DiscordRPC dedupes identical consecutive payloads** instead of
+  hammering the IPC channel on every poll. The daemon ticks every
+  500 ms but Discord rate-limits presence updates to 5 per 20 s, so
+  ~75 % of those ticks were silently being dropped on the Discord
+  side anyway. Now the second-and-on identical payload is a no-op
+  on our side too.
+- **Cover-wait defer back to 3 polls (~1.5 s)**. v0.2.2 lowered it
+  to 1 poll to feel more "live", but that meant Discord briefly
+  rendered the `refrain` brand fallback as the *large* image while
+  iTunes search returned, then flipped to the cover — visible
+  flicker on every track change. With 3 polls Discord typically
+  transitions straight from "no activity" to the cover with no
+  flash. Bounded: songs that have no iTunes match still update
+  after 1.5 s with the brand fallback.
+- **Tray menu's "Update available" line now carries a coloured
+  icon** (Breeze accent blue, `assets/icons/menu-update.svg`)
+  instead of just a unicode `⬆` arrow in the same white as every
+  other line. Visually distinguishes the update notification from
+  Settings / Live log / Restart in the menu's icon column.
+- **Browser hint defaults expanded** with Floorp, Waterfox, Mullvad
+  Browser, Tor Browser and ungoogled-chromium. Existing configs
+  keep their saved list (no auto-migration); the new entries appear
+  unticked in Settings → Sources until the user toggles them.
+- **~20 English-only UI strings wrapped in `tr()`** —
+  `update_dialog.py` (status labels, button labels, header HTML),
+  `log_window.py` (toolbar Level/Auto-scroll/Copy/Clear/Close), and
+  `app.py` module-level QMessageBox calls (now via
+  `QCoreApplication.translate`). Re-ran `lupdate6` + `lrelease6`
+  against `refrain_de.ts`: 127/127 finished German translations.
+- **`docs/architecture.md` refreshed** to v0.2.x reality — the
+  diagram showed a "1 Hz tick" (default has been 500 ms since
+  v0.2.2), the worker-thread block was missing `MPRISServer`, the
+  GLib thread for dbus-python signal dispatch was undocumented, and
+  the "does not export any custom interfaces" line was wrong since
+  the v0.2.2 MPRIS-server publication. Plus a new section on
+  Discord IPC sandbox bridging (Snap/Flatpak).
+
+### Fixed
+
+- **Tray tooltip cleared on track change.** After a paused-to-paused
+  track switch, the tooltip briefly showed "Song B • 1:30 / 2:11"
+  using Song A's elapsed counter while the new track waited for its
+  first `progressTick`. `set_track` now drops the stale progress
+  line when the title text actually changed.
+- **`compute_idle_state` honours the iTunes-corrected duration.**
+  Previously the deadline keyed off `track.duration_ms` so a
+  7:21-playlist-total-on-a-2:11-song lie made dangling-tab cleanup
+  fire 5 minutes too late. New optional `effective_duration_ms`
+  parameter; the daemon passes the same value the RPC payload
+  uses.
+- **Snap and Flatpak Discord builds reachable out of the box.**
+  Their IPC socket lives inside the sandbox tree
+  (`$XDG_RUNTIME_DIR/app/com.discordapp.Discord/`,
+  `~/.var/app/com.discordapp.Discord/config/discord/`,
+  `~/snap/discord/current/.config/discord/`), so pypresence's stock
+  discovery never finds it. `_bridge_sandboxed_ipc_socket` symlinks
+  the first sandbox socket it finds into `$XDG_RUNTIME_DIR` before
+  each connect attempt, and sweeps stale symlinks left behind when
+  the sandbox path's target is removed (Snap uninstall, Flatpak
+  remove, host reboot).
+- **Config drops unknown TOML keys instead of nuking the whole
+  file.** A single typo or a key written by a *newer* Refrain that
+  the user has since downgraded from used to make
+  `Config.from_dict` raise `TypeError`, caught by the surrounding
+  `except` and falling back to defaults for *every* setting.
+  `_construct()` now filters the payload through dataclass fields
+  before `**`-splatting; the offending keys get a single WARNING in
+  the log naming the section, the rest of the section survives.
+- **Stale comments + doc references cleaned up.** Four "1 Hz" call-
+  outs in `mpris.py` / `daemon.py` (default has been 500 ms since
+  v0.2.2), plus one reference to the AppImage runtime that no
+  longer matches the AppRun layout.
+
+### Tests
+
+- **+13 unit tests** covering the new helpers — `DiscordRPC` payload
+  dedup (4), `_bridge_sandboxed_ipc_socket` (4), `compute_idle_state`
+  with `effective_duration_ms` (2), `cleanup_orphan_downloads` (3).
+  Total: 113 → 125, all green, ruff + bandit + pip-audit clean,
+  Dependabot 0 outstanding alerts.
+
+## [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 +812,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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refrain
-Version: 0.2.2
+Version: 0.2.4
 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
 
@@ -318,6 +319,8 @@ tray + controls running.
 
 - [Architecture overview](docs/architecture.md) — threads, D-Bus surface, file paths
 - [FAQ](docs/faq.md)
+- [Bluetooth quick-start](docs/bluetooth.md) — pair + AVRCP setup walkthrough
+- [Test matrix](docs/test-matrix.md) — supported distros, smoke-check checklist
 - [Roadmap](ROADMAP.md)
 - [Changelog](CHANGELOG.md)
 - [Contributing](CONTRIBUTING.md) — dev setup, testing, code style

{refrain-0.2.2 → refrain-0.2.4}/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
 
@@ -284,6 +285,8 @@ tray + controls running.
 
 - [Architecture overview](docs/architecture.md) — threads, D-Bus surface, file paths
 - [FAQ](docs/faq.md)
+- [Bluetooth quick-start](docs/bluetooth.md) — pair + AVRCP setup walkthrough
+- [Test matrix](docs/test-matrix.md) — supported distros, smoke-check checklist
 - [Roadmap](ROADMAP.md)
 - [Changelog](CHANGELOG.md)
 - [Contributing](CONTRIBUTING.md) — dev setup, testing, code style

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

@@ -169,6 +169,120 @@ 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).
+
+## Done — v0.2.4
+
+- **Time-display consistency across tray + Plasma panel + Discord**.
+  v0.2.3 already fixed Discord; the tray's progress label and the
+  published MPRIS Metadata still keyed off the raw `mpris:length`
+  and showed inconsistent numbers when MPRIS briefly lied about a
+  song's duration. `pick_effective_duration_ms` is now hoisted into
+  `_dispatch` so all three surfaces see the same iTunes-corrected
+  value every tick. Plus position is clamped to duration so a
+  "2:30 / 0:14 (-0:00)" line can't render during a brief MPRIS
+  preview-clip glitch.
+- **Snap and Flatpak Discord builds reachable out of the box**.
+  Their IPC socket lives inside the sandbox tree
+  (`xdg-run/app/com.discordapp.Discord/`,
+  `~/.var/app/com.discordapp.Discord/.../`,
+  `~/snap/discord/current/.config/discord/`) which pypresence
+  doesn't probe. `_bridge_sandboxed_ipc_socket` symlinks the first
+  sandbox socket it finds into `$XDG_RUNTIME_DIR` before each
+  connect attempt + sweeps stale symlinks left behind when the
+  Discord install is removed.
+- **Inline release notes in Settings → Updates tab**. The tab
+  carries a QTextBrowser that renders the same Markdown as the
+  popup, plus "Current version" + "Latest known" labels.
+  `releaseInfoFetched(release | None)` signal fires after every
+  check (auto / manual, success / failure) so the tab refreshes
+  regardless of the result.
+- **Discord activity card always shows the Refrain brand badge as
+  small_image**. Previously the badge was only in `large_image` as
+  a fallback when cover-art lookup failed; now it's the small-icon
+  corner of every payload, so the cover gets the visual focus and
+  hovering reveals "Refrain" as the source app. Plus the
+  cover-wait defer is back to 3 polls (~1.5 s at 500 ms tick) so
+  Discord usually goes straight from "no activity" to "cover" with
+  no brand flash on the way.
+- **Config drops unknown TOML keys** instead of nuking the whole
+  file. A typo or a key written by a newer Refrain that the user
+  has since downgraded from used to make `Config.from_dict` raise,
+  caught by the surrounding except, and fall back to defaults for
+  every setting. Now the offending key gets a single warning, the
+  rest of the section survives.
+- **DiscordRPC dedupes identical consecutive payloads**. The
+  daemon ticks every 500 ms but Discord rate-limits presence
+  updates to 5/20 s — most ticks were silently dropped on the
+  Discord side anyway. Now the second-and-on identical payload
+  is a no-op on our side too.
+- **Browser hints expanded**: Floorp, Waterfox, Mullvad Browser,
+  Tor Browser, ungoogled-chromium.
+- **`docs/bluetooth.md`** — first-time-setup walkthrough covering
+  bluez install per distro, pairing recipe, AVRCP verification,
+  per-source Discord profile setup, and Troubleshooting.
+- **FAQ entries** for "Refrain isn't picking up my browser"
+  (covers `playerctl` diagnostic + Snap-confined-browser workaround
+  + Firefox `about:config` toggle) and "How do I add a browser
+  that isn't in the list".
+- **`docs/architecture.md` refreshed** to v0.2.x reality — diagram
+  no longer claims "1 Hz tick" (default has been 500 ms since
+  v0.2.2), `MPRISServer` block added, `org.mpris.MediaPlayer2.refrain`
+  publish documented, GLib thread for dbus-python signal dispatch
+  documented, new section on Discord IPC sandbox bridging.
+- **+13 unit tests**: `DiscordRPC` payload dedup (4),
+  `_bridge_sandboxed_ipc_socket` (4), `compute_idle_state` with
+  `effective_duration_ms` (2), `cleanup_orphan_downloads` (3).
+  Total: 113 → 125, all green.
+
 ## Up next — v0.3
 
 - **Polishing the wrapped i18n surface** — wrap the remaining

{refrain-0.2.2 → refrain-0.2.4}/docs/architecture.md

@@ -11,26 +11,33 @@ Refrain is one process with two threads and one external IPC socket.
 │  ├─ TrayIcon (QSystemTrayIcon)         ←─── status / track      │
 │  ├─ SettingsWindow (QDialog, hidden after Apply)                │
 │  ├─ LogWindow (QDialog, on-demand)                              │
+│  ├─ WelcomeDialog (first-run only)                              │
 │  ├─ UpdateOrchestrator                                          │
 │  └─ UpdateDialog                                                │
 │                                                                 │
 │  Worker thread (Qt event loop, QThread)                         │
 │  ├─ DaemonWorker                                                │
-│  │    ├─ MPRISSource         ──► Session DBus                   │
+│  │    ├─ MPRISSource         ──► Session DBus (read)            │
 │  │    ├─ BluetoothSource     ──► System DBus (org.bluez)        │
 │  │    ├─ CoverFetcher        ──► iTunes Search (HTTPS)          │
-│  │    └─ DiscordRPC          ──► Discord IPC socket             │
-│  └─ Timer (QTimer, 1 Hz tick)                                   │
+│  │    ├─ DiscordRPC          ──► Discord IPC socket             │
+│  │    └─ MPRISServer         ──► Session DBus (publish own)     │
+│  └─ Timer (QTimer, 500 ms default poll, configurable)           │
+│                                                                 │
+│  GLib thread (only when PyGObject is available)                 │
+│  └─ GLib.MainLoop — pumps dbus-python signals so Plasma's panel │
+│     PlayPause / Next / Previous reach our MPRISServer methods.  │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
 ## Why a worker thread?
 
-The polling loop (1 Hz) reads MPRIS / BlueZ properties via D-Bus. Some of
-those calls block briefly. iTunes Search lookups can take up to 5 s.
-Discord IPC writes can stall when Discord is restarting. Doing any of
-that on the GUI thread would make the tray icon and settings window
-freeze every poll.
+The polling loop (default 500 ms, configurable via
+`advanced.poll_interval_ms`) reads MPRIS / BlueZ properties via D-Bus.
+Some of those calls block briefly. iTunes Search lookups can take up
+to 5 s. Discord IPC writes can stall when Discord is restarting.
+Doing any of that on the GUI thread would make the tray icon and
+settings window freeze every poll.
 
 The worker thread runs a Qt event loop (driven by `QTimer`, *not* a
 `while/sleep` loop — that detail matters: a sleep loop blocks the event
@@ -84,6 +91,30 @@ to `/usr/share/applications/refrain.desktop` instead.
 | `org.mpris.MediaPlayer2.Player`         | session| Track metadata + Play/Next/Prev   |
 | `org.bluez.MediaPlayer1`                | system | AVRCP track + Play/Pause/Next/Prev|
 | `org.bluez.Device1` (via ObjectManager) | system | Paired-device enumeration         |
+| `org.freedesktop.DBus.NameHasOwner`     | system | Fast-fail check before activating `org.bluez` (avoids a 25 s service-activation timeout on hosts without bluez)|
+
+## D-Bus interfaces published
+
+Refrain publishes two well-known names on the **session** bus:
+
+| Bus name                              | Purpose                                        |
+|---------------------------------------|------------------------------------------------|
+| `io.github.Rockykln.Refrain`          | Single-instance lock. No object path; just the name reservation. |
+| `org.mpris.MediaPlayer2.refrain`      | Refrain itself as an MPRIS player. KDE Plasma's panel media controls applet, KDE Connect, GNOME Shell etc. drive the same Play/Pause/Next/Previous as the tray, and render the same track Discord renders. Implements the standard MPRIS root + Player interfaces. |
+
+The MPRIS-server publication needs PyGObject (`gi`) for a GLib main loop
+to pump dbus-python signal dispatch. When PyGObject isn't installed,
+Refrain logs a warning at startup and falls back to read-only mode —
+the rest of the app works, but Plasma's panel can't drive playback.
+
+## Discord IPC discovery
 
-Refrain also registers exactly one well-known name on the session bus
-for the single-instance lock; it does not export any custom interfaces.
+The standard path is `$XDG_RUNTIME_DIR/discord-ipc-N` (N=0..9). Snap
+and Flatpak Discord builds put their socket inside the sandbox tree
+instead (`$XDG_RUNTIME_DIR/app/com.discordapp.Discord/discord-ipc-N`,
+`~/.var/app/com.discordapp.Discord/config/discord/discord-ipc-N`,
+`~/snap/discord/current/.config/discord/discord-ipc-N`).
+`DiscordRPC._bridge_sandboxed_ipc_socket` symlinks the first sandbox
+socket it finds into `$XDG_RUNTIME_DIR` before each connect attempt,
+and sweeps stale symlinks left behind by previously-uninstalled
+Discord builds.