From f388c31ff09fd4b7d4e705bf55f0660c11ad76b2 Mon Sep 17 00:00:00 2001
From: EmreSoyak <emresoyak@gmail.com>
Date: Wed, 15 Apr 2026 18:58:33 +0300
Subject: [PATCH 1/2] feat: Add virtual desktop, audio-only, playback recovery,
 and tray hover mini-player

Custom feature pack by EmreSoyak:

- Virtual Desktop Awareness: Window moves to current virtual desktop
  instead of yanking you back (Options > Tray toggle)
- Audio-Only Plugin: Forces audio-only streaming, saves ~300MB RAM
- Playback Recovery Plugin: Auto-recovers from stuck/stalled playback
  with progressive strategies (seek, seek-forward, skip)
- Tray Hover Mini-Player: Hover the tray icon to see album art,
  song info, and prev/play-pause/next controls
- Toast suppression when hover popup is active
- Deferred tray event handlers (fixes plugin-before-tray init order)
- DevTools gated behind OPEN_DEVTOOLS env var

See EMRE-FEATURES.md for full documentation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 EMRE-FEATURES.md                         | 307 +++++++++++++++++++++++
 assets/hover-popup.html                  | 138 ++++++++++
 src/config/defaults.ts                   |   2 +
 src/i18n/resources/en.json               |  13 +
 src/index.ts                             |  14 +-
 src/menu.ts                              |  13 +
 src/plugins/audio-only/index.ts          | 133 ++++++++++
 src/plugins/notifications/hover-popup.ts | 236 +++++++++++++++++
 src/plugins/notifications/index.ts       |   2 +
 src/plugins/notifications/interactive.ts |   6 +-
 src/plugins/notifications/main.ts        |   5 +
 src/plugins/notifications/menu.ts        |   9 +
 src/plugins/playback-recovery/index.ts   | 306 ++++++++++++++++++++++
 src/tray.ts                              |  57 ++++-
 src/window-utils.ts                      |  12 +
 15 files changed, 1245 insertions(+), 8 deletions(-)
 create mode 100644 EMRE-FEATURES.md
 create mode 100644 assets/hover-popup.html
 create mode 100644 src/plugins/audio-only/index.ts
 create mode 100644 src/plugins/notifications/hover-popup.ts
 create mode 100644 src/plugins/playback-recovery/index.ts
 create mode 100644 src/window-utils.ts

diff --git a/EMRE-FEATURES.md b/EMRE-FEATURES.md
new file mode 100644
index 0000000000..6e1d89b183
--- /dev/null
+++ b/EMRE-FEATURES.md
@@ -0,0 +1,307 @@
+# Emre's YouTube Music Player - Custom Features
+
+A collection of custom features and enhancements for [th-ch/youtube-music](https://github.com/th-ch/youtube-music), focused on virtual desktop workflows, memory optimization, playback reliability, and tray UX improvements.
+
+---
+
+## Table of Contents
+
+1. [Audio-Only Mode](#1-audio-only-mode) (Plugin)
+2. [Playback Recovery](#2-playback-recovery) (Plugin)
+3. [Virtual Desktop Awareness](#3-virtual-desktop-awareness) (Core setting)
+4. [Tray Hover Mini-Player](#4-tray-hover-mini-player) (Notification plugin extension)
+5. [DevTools Control](#5-devtools-control) (Core tweak)
+6. [Diagnostic Tools](#6-diagnostic-tools) (External scripts)
+7. [Build & Launch Scripts](#7-build--launch-scripts)
+
+---
+
+## 1. Audio-Only Mode
+
+**Type:** Plugin
+**Location:** `src/plugins/audio-only/index.ts`
+**Toggle:** Settings > Plugins > Audio Only (requires restart)
+**Default:** Off
+
+### What it does
+
+Forces YouTube Music to stream audio only, eliminating video decoding and buffering entirely. This cuts memory usage by roughly 300+ MB.
+
+### How it works
+
+1. Sets `playback-mode="ATV_PREFERRED"` on the `ytmusic-player` element (tells YouTube this is an audio-only device)
+2. Calls `moviePlayer.setPlaybackQuality('tiny')` and `setPlaybackQualityRange('tiny')` via the internal player API
+3. Hides the `<video>` element and the `#song-video` container, forces album art (`#song-image`) visible
+4. Uses a `MutationObserver` to lock the `playback-mode` attribute — YouTube periodically tries to flip it back to `OMV_PREFERRED`; this prevents that
+5. Re-applies on every song change via the `videodatachange` event
+
+### Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable audio-only mode |
+
+---
+
+## 2. Playback Recovery
+
+**Type:** Plugin
+**Location:** `src/plugins/playback-recovery/index.ts`
+**Toggle:** Settings > Plugins > Playback Recovery
+**Default:** Off
+
+### What it does
+
+Automatically detects and recovers from stuck, stalled, or dead playback states. When YouTube Music's player freezes (which happens regularly), this plugin intervenes without user action.
+
+### How it works
+
+**Watchdog (runs every 3 seconds):**
+- Checks if `readyState === 0` while the player reports "playing" (completely dead)
+- Checks if `currentTime` hasn't advanced while not paused (frozen playback)
+- Checks if buffered data is exhausted while playing
+
+**Media event hooks:**
+- `error` — immediate recovery attempt on media errors
+- `stalled` — waits for the stall timeout, then recovers if unresolved
+- `waiting` — monitors if buffering persists too long
+- `timeupdate` — tracks healthy playback (resets failure counters)
+
+**MutationObserver:**
+- Watches for the `<video>` element being removed and recreated by YouTube's player
+- Re-attaches recovery hooks to the new element automatically
+
+**Recovery strategies (progressive):**
+1. **Seek to current position** (attempts 1-2) — forces buffer reload
+2. **Seek forward 1 second** (attempts 3-4) — gets past potentially corrupt segments
+3. **Skip to next track** (after max retries) — gives up on the current song
+
+### Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable playback recovery |
+| `stallTimeoutMs` | number | `8000` | Milliseconds before a stall triggers recovery |
+| `maxRetries` | number | `5` | Max recovery attempts before skipping the track |
+| `logToConsole` | boolean | `true` | Log recovery events to the DevTools console |
+
+### Menu
+
+- **Log recovery events to console** (checkbox) — under the plugin's settings
+
+---
+
+## 3. Virtual Desktop Awareness
+
+**Type:** Core setting (not a plugin)
+**Location:** `src/window-utils.ts`, `src/tray.ts`, `src/index.ts`
+**Toggle:** Options > Tray > "Move to current virtual desktop on show"
+**Default:** Off
+
+### What it does
+
+When enabled, clicking the tray icon (or launching a second instance) **moves the YouTube Music window to your current virtual desktop** instead of yanking you back to the desktop where the window originally opened.
+
+### How it works
+
+Uses Electron's `setVisibleOnAllWorkspaces` API:
+1. `win.setVisibleOnAllWorkspaces(true)` — temporarily pins the window to all desktops (makes it appear on the current one)
+2. `win.show()` — shows and focuses the window
+3. `win.setVisibleOnAllWorkspaces(false)` — unpins it, leaving it on the current desktop
+
+**Applied at 3 call sites:**
+- Tray icon single-click (show window)
+- Tray right-click menu > "Show"
+- Second-instance handler (when you double-click the app shortcut while it's already running)
+
+### Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `options.trayMoveToCurrentDesktop` | boolean | `false` | Move window to current virtual desktop on show |
+
+---
+
+## 4. Tray Hover Mini-Player
+
+**Type:** Notification plugin extension
+**Location:** `src/plugins/notifications/hover-popup.ts`, `assets/hover-popup.html`
+**Toggle:** Notifications plugin > Interactive Settings > "Show mini-player on tray hover"
+**Default:** Off
+**Prerequisite:** Notifications plugin must be enabled
+
+### What it does
+
+When you hover over the YouTube Music tray icon, a compact floating mini-player appears showing the current song's album art, title, artist, and playback controls (previous / play-pause / next). The popup stays visible as long as your mouse is on the tray icon or on the popup itself, then fades out when you move away.
+
+This solves the problem of YouTube Music's native toast notifications disappearing after 5 seconds before you can interact with them.
+
+### How it works
+
+**Popup window:**
+- Frameless, transparent, always-on-top `BrowserWindow` (380x85 content area)
+- Dark theme matching YouTube Music's aesthetic (#282828 background)
+- Positioned above the tray icon, centered
+- Uses `setIgnoreMouseEvents(true, { forward: true })` for transparent areas (click-through) and toggles to `setIgnoreMouseEvents(false)` when mouse enters the popup card
+
+**Hover tracking:**
+- `tray.on('mouse-move')` detects when the cursor is over the tray icon
+- When `mouse-move` stops firing for 300ms, the tray is considered "left"
+- The popup's HTML tracks `mouseenter`/`mouseleave` on the card itself
+- A 400ms grace period allows moving between tray and popup without dismissing
+- Communication between HTML and main process uses `console.log('__IPC__:...')` messages intercepted via `webContents.on('console-message')`
+
+**Song info:**
+- Registers its own `registerCallback` for song change events
+- Pushes updates to the popup via `webContents.executeJavaScript()`
+
+### Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `hoverControls` | boolean | `false` | Show mini-player popup on tray hover |
+
+---
+
+## 5. DevTools Control
+
+**Type:** Core tweak
+**Location:** `src/index.ts` (line ~315)
+**Toggle:** Environment variable `OPEN_DEVTOOLS=1`
+**Default:** DevTools do NOT auto-open in dev mode
+
+### What it does
+
+By default in the upstream repo, DevTools auto-open whenever you run in dev mode. This change gates that behind an environment variable so DevTools only open when explicitly requested.
+
+### How to use
+
+- **Normal dev mode:** `pnpm dev` — DevTools stay closed
+- **With DevTools:** `OPEN_DEVTOOLS=1 pnpm dev`
+- **Manual toggle:** Press `Ctrl+Shift+I` at any time in the running app
+
+---
+
+## 6. Diagnostic Tools
+
+External scripts for debugging playback issues without modifying the app's source code. These connect via Chrome DevTools Protocol (CDP) when the app is launched with `--remote-debugging-port=9222`.
+
+### monitor.cjs
+
+**Location:** `monitor.cjs` (root)
+**Purpose:** Real-time playback diagnostics
+
+Connects to the running app via CDP and monitors:
+- All media events (play, pause, error, stalled, waiting, ended, etc.)
+- Flicker detection (rapid play/pause cycling)
+- Video element recreation
+- "Are you still listening?" popup detection
+- Network failures on media resources
+- ReadyState drops and buffer exhaustion
+
+Output is color-coded with tags: `INFO`, `PLAY`, `PAUSE`, `WARN`, `ERROR`, `EVENT`, `DIALOG`, `NET`, `CONSOLE`.
+
+**Usage:** `node monitor.cjs` (while app runs with debug port)
+
+### inject-lightweight.cjs
+
+**Location:** `inject-lightweight.cjs` (root)
+**Purpose:** Runtime audio-only injection (non-permanent alternative to the Audio-Only plugin)
+
+Injects via CDP to:
+1. Block 68+ video stream URLs (itag 13-702) from googlevideo.com using `Network.setBlockedURLs`
+2. Intercept `fetch()` calls and return 204 for video MIME types
+3. Force `playback-mode="ATV_PREFERRED"`
+4. Hide video element, show album art
+5. Run periodic buffer monitoring (logs every 30s)
+
+**Usage:** `node inject-lightweight.cjs` (while app runs with debug port)
+
+> **Note:** The Audio-Only plugin (feature #1) is the permanent, built-in version of this. Use `inject-lightweight.cjs` only for one-off testing without rebuilding.
+
+---
+
+## 7. Build & Launch Scripts
+
+### build.bat
+
+**Location:** `build.bat` (root)
+
+One-click rebuild: `pnpm clean` > `pnpm build` > `pnpm electron-builder --win dir:x64 -p never`
+
+Output: `pack\win-unpacked\YouTube Music.exe`
+
+### start.bat
+
+**Location:** `start.bat` (root)
+
+Launches the built exe from `pack\win-unpacked\YouTube Music.exe`.
+
+### diagnose.bat
+
+**Location:** `diagnose.bat` (root)
+
+Launches the app with `--remote-debugging-port=9222` and starts `monitor.cjs` for live playback diagnostics.
+
+### Icon & Shortcut Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `make-icon.ps1` | Converts `assets/icon.png` to `icon.ico` (multi-size) |
+| `update-shortcut.ps1` | Creates/updates desktop shortcut pointing to the built exe with the custom icon |
+| `pin-shortcut.ps1` | Old dev-mode shortcut script (obsolete) |
+
+---
+
+## File Map
+
+All custom files at a glance:
+
+```
+z_youtube_player/
+  EMRE-FEATURES.md              <- This file
+  build.bat                      <- Build script
+  start.bat                      <- Launch script
+  diagnose.bat                   <- Debug launcher
+  monitor.cjs                    <- CDP playback monitor
+  inject-lightweight.cjs         <- CDP audio-only injector
+  icon.ico                       <- Custom app icon
+  make-icon.ps1                  <- Icon generator
+  update-shortcut.ps1            <- Shortcut updater
+  pin-shortcut.ps1               <- (obsolete)
+  assets/
+    hover-popup.html             <- Tray hover mini-player UI
+  src/
+    window-utils.ts              <- Virtual desktop helper
+    plugins/
+      audio-only/
+        index.ts                 <- Audio-Only plugin
+      playback-recovery/
+        index.ts                 <- Playback Recovery plugin
+      notifications/
+        hover-popup.ts           <- Tray hover mini-player logic
+  Modified core files:
+    src/index.ts                 <- DevTools gate + virtual desktop
+    src/tray.ts                  <- Virtual desktop + mouse-move support
+    src/config/defaults.ts       <- trayMoveToCurrentDesktop option
+    src/menu.ts                  <- Virtual desktop menu item
+    src/i18n/resources/en.json   <- All new labels
+    src/plugins/notifications/
+      index.ts                   <- hoverControls config
+      main.ts                    <- Hover popup wiring
+      menu.ts                    <- Hover controls menu item
+```
+
+---
+
+## Feature Status Summary
+
+| # | Feature | Type | Toggle | Default |
+|---|---------|------|--------|---------|
+| 1 | Audio-Only Mode | Plugin | Plugin settings | Off |
+| 2 | Playback Recovery | Plugin | Plugin settings | Off |
+| 3 | Virtual Desktop Awareness | Core setting | Options > Tray | Off |
+| 4 | Tray Hover Mini-Player | Plugin extension | Notifications > Interactive Settings | Off |
+| 5 | DevTools Control | Core tweak | `OPEN_DEVTOOLS=1` env var | Off |
+| 6 | Diagnostic Tools | External scripts | Run manually | N/A |
+| 7 | Build Scripts | External scripts | Run manually | N/A |
diff --git a/assets/hover-popup.html b/assets/hover-popup.html
new file mode 100644
index 0000000000..65e08fa0fb
--- /dev/null
+++ b/assets/hover-popup.html
@@ -0,0 +1,138 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+*, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
+html, body {
+  background: transparent !important;
+  overflow: hidden;
+  width: 100%;
+  height: 100%;
+}
+body {
+  padding: 8px;
+  user-select: none;
+  font-family: 'Segoe UI', -apple-system, BlinkMacSystemFont, sans-serif;
+}
+#popup {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 14px;
+  background: #282828;
+  border-radius: 10px;
+  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.55);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  height: calc(100% - 0px);
+  opacity: 0;
+  transform: translateY(6px);
+  transition: opacity 0.2s ease, transform 0.2s ease;
+}
+#popup.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+#albumArt {
+  width: 56px;
+  height: 56px;
+  border-radius: 6px;
+  object-fit: cover;
+  flex-shrink: 0;
+  background: #333;
+}
+#info {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 3px;
+}
+#title {
+  color: #fff;
+  font-size: 13px;
+  font-weight: 600;
+  line-height: 1.3;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+#artist {
+  color: #aaa;
+  font-size: 11px;
+  line-height: 1.3;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+#controls {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  flex-shrink: 0;
+}
+.btn {
+  width: 36px;
+  height: 36px;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.15s;
+  padding: 0;
+}
+.btn:hover { background: rgba(255, 255, 255, 0.12); }
+.btn:active { background: rgba(255, 255, 255, 0.20); }
+.btn svg { width: 18px; height: 18px; fill: #fff; }
+.btn.pp svg { width: 22px; height: 22px; }
+</style>
+</head>
+<body>
+<div id="popup">
+  <img id="albumArt" />
+  <div id="info">
+    <div id="title">No song playing</div>
+    <div id="artist"></div>
+  </div>
+  <div id="controls">
+    <button class="btn" id="prev" title="Previous">
+      <svg viewBox="0 0 24 24"><path d="M6 6h2v12H6zM18 6v12l-8.5-6z"/></svg>
+    </button>
+    <button class="btn pp" id="pp" title="Play/Pause">
+      <svg viewBox="0 0 24 24" id="ppSvg"><path d="M8 5v14l11-7z"/></svg>
+    </button>
+    <button class="btn" id="next" title="Next">
+      <svg viewBox="0 0 24 24"><path d="M6 18l8.5-6L6 6v12zM16 6v12h2V6h-2z"/></svg>
+    </button>
+  </div>
+</div>
+<script>
+(function() {
+  var popup = document.getElementById('popup');
+
+  var n = 0;
+  document.getElementById('prev').onmousedown = function(e) { e.preventDefault(); document.title = 'act:previous:' + (++n); };
+  document.getElementById('next').onmousedown = function(e) { e.preventDefault(); document.title = 'act:next:' + (++n); };
+  document.getElementById('pp').onmousedown = function(e) { e.preventDefault(); document.title = 'act:playPause:' + (++n); };
+
+  window.updateSongInfo = function(data) {
+    document.getElementById('title').textContent = data.title || 'No song playing';
+    document.getElementById('artist').textContent = data.artist || '';
+    var art = document.getElementById('albumArt');
+    if (data.imageSrc) { art.src = data.imageSrc; art.style.display = ''; }
+    else { art.style.display = 'none'; }
+    document.getElementById('ppSvg').innerHTML = data.isPaused
+      ? '<path d="M8 5v14l11-7z"/>'
+      : '<path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z"/>';
+  };
+
+  window.showPopup = function() { popup.classList.add('visible'); };
+  window.hidePopup = function() { popup.classList.remove('visible'); };
+})();
+</script>
+</body>
+</html>
diff --git a/src/config/defaults.ts b/src/config/defaults.ts
index 9e4df88b01..030109f767 100644
--- a/src/config/defaults.ts
+++ b/src/config/defaults.ts
@@ -26,6 +26,7 @@ export interface DefaultConfig {
     removeUpgradeButton: boolean;
     restartOnConfigChanges: boolean;
     trayClickPlayPause: boolean;
+    trayMoveToCurrentDesktop: boolean;
     autoResetAppCache: boolean;
     resumeOnStart: boolean;
     likeButtons: string;
@@ -64,6 +65,7 @@ export const defaultConfig: DefaultConfig = {
     removeUpgradeButton: false,
     restartOnConfigChanges: false,
     trayClickPlayPause: false,
+    trayMoveToCurrentDesktop: false,
     autoResetAppCache: false,
     resumeOnStart: true,
     likeButtons: '',
diff --git a/src/i18n/resources/en.json b/src/i18n/resources/en.json
index 763e854b82..b0611748ff 100644
--- a/src/i18n/resources/en.json
+++ b/src/i18n/resources/en.json
@@ -144,6 +144,7 @@
               "disabled": "Disabled",
               "enabled-and-hide-app": "Enabled and hide app",
               "enabled-and-show-app": "Enabled and show app",
+              "move-to-current-desktop": "Move to current virtual desktop on show",
               "play-pause-on-click": "Play/Pause on click"
             }
           },
@@ -243,6 +244,10 @@
       },
       "name": "Album Color Theme"
     },
+    "audio-only": {
+      "description": "Forces audio-only mode — blocks all video streams at network and player level to save RAM and bandwidth",
+      "name": "Audio Only"
+    },
     "ambient-mode": {
       "description": "Applies a lighting effect by casting gentle colors from the video, into your screen’s background",
       "menu": {
@@ -684,6 +689,7 @@
           "label": "Interactive Settings",
           "submenu": {
             "hide-button-text": "Hide button text",
+            "hover-controls": "Show mini-player on tray hover",
             "refresh-on-play-pause": "Refresh on Play/Pause",
             "tray-controls": "Open/Close on tray click"
           }
@@ -698,6 +704,13 @@
       "description": "Improve performance by enabling experimental scripts",
       "name": "Performance improvement [Beta]"
     },
+    "playback-recovery": {
+      "description": "Automatically recovers from stuck, stalled, or dead playback states",
+      "menu": {
+        "log-to-console": "Log recovery events to console"
+      },
+      "name": "Playback Recovery"
+    },
     "picture-in-picture": {
       "description": "Allows to switch the app to picture-in-picture mode",
       "menu": {
diff --git a/src/index.ts b/src/index.ts
index 80fae3db0f..092ac40fe4 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -54,6 +54,7 @@ import {
 } from '@/loader/main';
 
 import { LoggerPrefix } from '@/utils';
+import { showOnCurrentDesktop } from '@/window-utils';
 import { APPLICATION_NAME, loadI18n, setLanguage, t } from '@/i18n';
 
 import ErrorHtmlAsset from '@assets/error.html?asset';
@@ -311,7 +312,7 @@ function initTheme(win: BrowserWindow) {
   }
 
   win.webContents.once('did-finish-load', () => {
-    if (is.dev()) {
+    if (is.dev() && process.env.OPEN_DEVTOOLS) {
       console.debug(LoggerPrefix, t('main.console.did-finish-load.dev-tools'));
       win.webContents.openDevTools();
     }
@@ -787,11 +788,14 @@ app.whenReady().then(async () => {
       mainWindow.restore();
     }
 
-    if (!mainWindow.isVisible()) {
-      mainWindow.show();
+    if (config.get('options.trayMoveToCurrentDesktop')) {
+      showOnCurrentDesktop(mainWindow);
+    } else {
+      if (!mainWindow.isVisible()) {
+        mainWindow.show();
+      }
+      mainWindow.focus();
     }
-
-    mainWindow.focus();
   });
 
   // Autostart at login
diff --git a/src/menu.ts b/src/menu.ts
index c08f62710c..e90bcf2934 100644
--- a/src/menu.ts
+++ b/src/menu.ts
@@ -478,6 +478,19 @@ export const mainMenuTemplate = async (
                 );
               },
             },
+            {
+              label: t(
+                'main.menu.options.submenu.tray.submenu.move-to-current-desktop',
+              ),
+              type: 'checkbox',
+              checked: config.get('options.trayMoveToCurrentDesktop'),
+              click(item: MenuItem) {
+                config.setMenuOption(
+                  'options.trayMoveToCurrentDesktop',
+                  item.checked,
+                );
+              },
+            },
           ],
         },
         {
diff --git a/src/plugins/audio-only/index.ts b/src/plugins/audio-only/index.ts
new file mode 100644
index 0000000000..30d02eacb9
--- /dev/null
+++ b/src/plugins/audio-only/index.ts
@@ -0,0 +1,133 @@
+import { createPlugin } from '@/utils';
+import { t } from '@/i18n';
+
+import type { MusicPlayer } from '@/types/music-player';
+import type { VideoDataChanged } from '@/types/video-data-changed';
+
+export type AudioOnlyConfig = {
+  enabled: boolean;
+};
+
+export default createPlugin<
+  unknown,
+  unknown,
+  {
+    api: MusicPlayer | null;
+    playbackModeObserver: MutationObserver | null;
+    videoDataListener: ((e: Event) => void) | null;
+  },
+  AudioOnlyConfig
+>({
+  name: () => t('plugins.audio-only.name'),
+  description: () => t('plugins.audio-only.description'),
+  restartNeeded: true,
+  config: {
+    enabled: false,
+  },
+  renderer: {
+    api: null,
+    playbackModeObserver: null,
+    videoDataListener: null,
+
+    start() {
+      // Hide video element, show album art
+      this.applyVisualMode();
+
+      // Lock playback-mode so YouTube can never flip it back
+      const player = document.querySelector<HTMLElement>('ytmusic-player');
+      if (player) {
+        player.setAttribute('playback-mode', 'ATV_PREFERRED');
+        player.style.margin = 'auto 0px';
+        this.lockPlaybackMode(player);
+      }
+    },
+
+    onPlayerApiReady(api) {
+      this.api = api;
+
+      // Force audio-only quality via the player API
+      this.setAudioOnly();
+
+      // Re-apply on every song change
+      this.videoDataListener = ((event: CustomEvent<VideoDataChanged>) => {
+        if (event.detail.name === 'dataloaded') {
+          this.setAudioOnly();
+          this.applyVisualMode();
+        }
+      }) as EventListener;
+
+      document.addEventListener('videodatachange', this.videoDataListener);
+      console.log('[audio-only] Renderer audio-only mode active');
+    },
+
+    stop() {
+      if (this.playbackModeObserver) {
+        this.playbackModeObserver.disconnect();
+        this.playbackModeObserver = null;
+      }
+      if (this.videoDataListener) {
+        document.removeEventListener('videodatachange', this.videoDataListener);
+        this.videoDataListener = null;
+      }
+    },
+
+    // --- Internal methods ---
+
+    setAudioOnly() {
+      // 1. Set playback-mode attribute
+      const player = document.querySelector<HTMLElement>('ytmusic-player');
+      if (player) {
+        player.setAttribute('playback-mode', 'ATV_PREFERRED');
+        player.style.margin = 'auto 0px';
+      }
+
+      // 2. Use player API to set lowest quality (triggers audio-only path)
+      try {
+        const moviePlayer = document.querySelector<any>('#movie_player');
+        if (moviePlayer) {
+          if (moviePlayer.setPlaybackQualityRange) {
+            moviePlayer.setPlaybackQualityRange('tiny');
+          }
+          if (moviePlayer.setPlaybackQuality) {
+            moviePlayer.setPlaybackQuality('tiny');
+          }
+        }
+      } catch (_) { /* ignore */ }
+
+      // 3. Hide the video element directly
+      this.applyVisualMode();
+    },
+
+    applyVisualMode() {
+      const songVideo = document.querySelector<HTMLElement>(
+        '#song-video.ytmusic-player',
+      );
+      const songImage = document.querySelector<HTMLElement>('#song-image');
+      if (songVideo) songVideo.style.display = 'none';
+      if (songImage) songImage.style.display = 'block';
+
+      // Also hide the actual video element to stop rendering
+      const video = document.querySelector<HTMLVideoElement>('video');
+      if (video) {
+        video.style.display = 'none';
+      }
+    },
+
+    lockPlaybackMode(player: HTMLElement) {
+      // Prevent YouTube from overriding playback-mode back to OMV_PREFERRED
+      this.playbackModeObserver = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          if (mutation.target instanceof HTMLElement) {
+            const current = mutation.target.getAttribute('playback-mode');
+            if (current !== 'ATV_PREFERRED') {
+              mutation.target.setAttribute('playback-mode', 'ATV_PREFERRED');
+            }
+          }
+        }
+      });
+      this.playbackModeObserver.observe(player, {
+        attributeFilter: ['playback-mode'],
+      });
+    },
+  },
+});
diff --git a/src/plugins/notifications/hover-popup.ts b/src/plugins/notifications/hover-popup.ts
new file mode 100644
index 0000000000..be0626611c
--- /dev/null
+++ b/src/plugins/notifications/hover-popup.ts
@@ -0,0 +1,236 @@
+import { BrowserWindow, screen, app } from 'electron';
+
+import HoverPopupAsset from '@assets/hover-popup.html?asset';
+
+import { getSongControls } from '@/providers/song-controls';
+import {
+  registerCallback,
+  type SongInfo,
+  SongInfoEvent,
+} from '@/providers/song-info';
+import { setTrayOnMouseMove, getTrayBounds } from '@/tray';
+
+const POPUP_WIDTH = 380;
+const POPUP_HEIGHT = 85;
+const SHADOW_PAD = 8;
+const GAP = 4;
+
+// Exported so interactive.ts can suppress toast notifications
+// while the hover popup is visible
+let _isVisible = false;
+export const isHoverPopupVisible = () => _isVisible;
+
+export const setupHoverPopup = (win: BrowserWindow) => {
+  const songControls = getSongControls(win);
+  let currentSongInfo: SongInfo | null = null;
+  let popup: BrowserWindow | null = null;
+  let popupReady = false;
+  let mouseTracker: ReturnType<typeof setInterval> | null = null;
+
+  const createPopup = () => {
+    popup = new BrowserWindow({
+      width: POPUP_WIDTH + SHADOW_PAD * 2,
+      height: POPUP_HEIGHT + SHADOW_PAD * 2,
+      frame: false,
+      transparent: true,
+      resizable: false,
+      skipTaskbar: true,
+      alwaysOnTop: true,
+      show: false,
+      webPreferences: {
+        nodeIntegration: false,
+        contextIsolation: true,
+      },
+    });
+
+    popup.loadFile(HoverPopupAsset);
+
+    popup.webContents.on('did-finish-load', () => {
+      popupReady = true;
+    });
+
+    // Button clicks from the popup HTML via document.title changes
+    popup.on('page-title-updated', (event, title) => {
+      if (!title.startsWith('act:')) return;
+      event.preventDefault();
+      const cmd = title.split(':')[1];
+
+      switch (cmd) {
+        case 'playPause':
+          songControls.playPause();
+          break;
+        case 'previous':
+          songControls.previous();
+          break;
+        case 'next':
+          songControls.next();
+          break;
+      }
+    });
+
+    popup.on('closed', () => {
+      popup = null;
+      popupReady = false;
+      _isVisible = false;
+      stopMouseTracking();
+    });
+  };
+
+  const positionPopup = () => {
+    if (!popup) return;
+
+    const bounds = getTrayBounds();
+    if (!bounds) return;
+
+    const display = screen.getDisplayNearestPoint({
+      x: bounds.x,
+      y: bounds.y,
+    });
+    const workArea = display.workArea;
+    const winW = POPUP_WIDTH + SHADOW_PAD * 2;
+    const winH = POPUP_HEIGHT + SHADOW_PAD * 2;
+
+    // Center horizontally on tray icon
+    let x = Math.round(bounds.x + bounds.width / 2 - winW / 2);
+    // Position above tray icon
+    let y = bounds.y - winH - GAP;
+
+    // Keep within screen bounds
+    x = Math.max(
+      workArea.x,
+      Math.min(x, workArea.x + workArea.width - winW),
+    );
+
+    // If tray is at top of screen, position below instead
+    if (bounds.y < workArea.y + workArea.height / 2) {
+      y = bounds.y + bounds.height + GAP;
+    }
+
+    y = Math.max(workArea.y, y);
+    popup.setPosition(x, y);
+  };
+
+  const isCursorOver = (bounds: Electron.Rectangle): boolean => {
+    const cursor = screen.getCursorScreenPoint();
+    return (
+      cursor.x >= bounds.x &&
+      cursor.x <= bounds.x + bounds.width &&
+      cursor.y >= bounds.y &&
+      cursor.y <= bounds.y + bounds.height
+    );
+  };
+
+  // Poll cursor position every 150ms while popup is visible.
+  // If mouse is on neither the popup nor the tray icon, hide.
+  const startMouseTracking = () => {
+    if (mouseTracker) return;
+    mouseTracker = setInterval(() => {
+      if (!popup || !_isVisible) {
+        stopMouseTracking();
+        return;
+      }
+
+      const overPopup = isCursorOver(popup.getBounds());
+      const trayBounds = getTrayBounds();
+      const overTray = trayBounds ? isCursorOver(trayBounds) : false;
+
+      if (!overPopup && !overTray) {
+        doHide();
+        stopMouseTracking();
+      }
+    }, 150);
+  };
+
+  const stopMouseTracking = () => {
+    if (mouseTracker) {
+      clearInterval(mouseTracker);
+      mouseTracker = null;
+    }
+  };
+
+  const doShow = () => {
+    if (!popup) createPopup();
+    if (!popup || !currentSongInfo) return;
+
+    positionPopup();
+
+    if (!_isVisible) {
+      popup.showInactive();
+      _isVisible = true;
+      startMouseTracking();
+    }
+
+    if (popupReady) {
+      pushSongInfo();
+      popup.webContents
+        .executeJavaScript('window.showPopup()')
+        .catch(() => {});
+    }
+  };
+
+  const doHide = () => {
+    if (!popup || !_isVisible) return;
+
+    if (popupReady) {
+      popup.webContents
+        .executeJavaScript('window.hidePopup()')
+        .catch(() => {});
+    }
+
+    // Wait for CSS fade-out animation before hiding the window
+    setTimeout(() => {
+      if (popup && _isVisible) {
+        // Final check: is the cursor back on popup or tray?
+        const overPopup = isCursorOver(popup.getBounds());
+        const trayBounds = getTrayBounds();
+        const overTray = trayBounds ? isCursorOver(trayBounds) : false;
+        if (overPopup || overTray) {
+          // Cursor came back, re-show and resume tracking
+          popup.webContents
+            .executeJavaScript('window.showPopup()')
+            .catch(() => {});
+          startMouseTracking();
+          return;
+        }
+
+        popup.hide();
+        _isVisible = false;
+      }
+    }, 250);
+  };
+
+  const pushSongInfo = () => {
+    if (!popup || !popupReady || !currentSongInfo) return;
+
+    const data = JSON.stringify({
+      title: currentSongInfo.title,
+      artist: currentSongInfo.artist,
+      imageSrc: currentSongInfo.imageSrc || '',
+      isPaused: currentSongInfo.isPaused ?? false,
+    });
+
+    popup.webContents
+      .executeJavaScript(`window.updateSongInfo(${data})`)
+      .catch(() => {});
+  };
+
+  // Tray hover triggers popup
+  setTrayOnMouseMove(() => {
+    doShow();
+  });
+
+  // Track current song info
+  registerCallback((songInfo, event) => {
+    if (event === SongInfoEvent.TimeChanged) return;
+    if (!songInfo.artist && !songInfo.title) return;
+
+    currentSongInfo = { ...songInfo };
+    if (_isVisible) pushSongInfo();
+  });
+
+  // Cleanup on quit
+  app.once('before-quit', () => {
+    stopMouseTracking();
+    popup?.close();
+  });
+};
diff --git a/src/plugins/notifications/index.ts b/src/plugins/notifications/index.ts
index a862f63150..3b2f9584ec 100644
--- a/src/plugins/notifications/index.ts
+++ b/src/plugins/notifications/index.ts
@@ -22,6 +22,7 @@ export interface NotificationsPluginConfig {
   refreshOnPlayPause: boolean;
   trayControls: boolean;
   hideButtonText: boolean;
+  hoverControls: boolean;
 }
 
 export const defaultConfig: NotificationsPluginConfig = {
@@ -33,6 +34,7 @@ export const defaultConfig: NotificationsPluginConfig = {
   refreshOnPlayPause: false,
   trayControls: true,
   hideButtonText: false,
+  hoverControls: true,
 };
 
 export default createPlugin({
diff --git a/src/plugins/notifications/interactive.ts b/src/plugins/notifications/interactive.ts
index 9376b35b33..2ff9f810a7 100644
--- a/src/plugins/notifications/interactive.ts
+++ b/src/plugins/notifications/interactive.ts
@@ -6,6 +6,7 @@ import nextIcon from '@assets/media-icons-black/next.png?asset&asarUnpack';
 import previousIcon from '@assets/media-icons-black/previous.png?asset&asarUnpack';
 
 import { notificationImage, secondsToMinutes, ToastStyles } from './utils';
+import { isHoverPopupVisible } from './hover-popup';
 
 import { getSongControls } from '@/providers/song-controls';
 import {
@@ -282,7 +283,10 @@ export default (
       (songInfo.url !== lastUrl || config().unpauseNotification)
     ) {
       lastUrl = songInfo.url;
-      sendNotification(songInfo);
+      // Don't show toast when hover popup is already visible
+      if (!isHoverPopupVisible()) {
+        sendNotification(songInfo);
+      }
     }
   });
 
diff --git a/src/plugins/notifications/main.ts b/src/plugins/notifications/main.ts
index ba1831a7ec..81d25b7948 100644
--- a/src/plugins/notifications/main.ts
+++ b/src/plugins/notifications/main.ts
@@ -4,6 +4,7 @@ import is from 'electron-is';
 
 import { notificationImage } from './utils';
 import interactive from './interactive';
+import { setupHoverPopup } from './hover-popup';
 
 import {
   registerCallback,
@@ -60,6 +61,10 @@ export const onMainLoad = async (
   if (is.windows() && config.interactive)
     interactive(context.window, () => config, context);
   else setup();
+
+  if (config.hoverControls) {
+    setupHoverPopup(context.window);
+  }
 };
 
 export const onConfigChange = (newConfig: NotificationsPluginConfig) => {
diff --git a/src/plugins/notifications/menu.ts b/src/plugins/notifications/menu.ts
index a9cdfe5eb9..b4eccd77b1 100644
--- a/src/plugins/notifications/menu.ts
+++ b/src/plugins/notifications/menu.ts
@@ -85,6 +85,15 @@ export const onMenu = async ({
               click: (item: MenuItem) =>
                 setConfig({ refreshOnPlayPause: item.checked }),
             },
+            {
+              label: t(
+                'plugins.notifications.menu.interactive-settings.submenu.hover-controls',
+              ),
+              type: 'checkbox',
+              checked: config.hoverControls,
+              click: (item: MenuItem) =>
+                setConfig({ hoverControls: item.checked }),
+            },
           ],
         },
         {
diff --git a/src/plugins/playback-recovery/index.ts b/src/plugins/playback-recovery/index.ts
new file mode 100644
index 0000000000..165a81eddb
--- /dev/null
+++ b/src/plugins/playback-recovery/index.ts
@@ -0,0 +1,306 @@
+import { createPlugin } from '@/utils';
+import { t } from '@/i18n';
+
+import type { MusicPlayer } from '@/types/music-player';
+
+export type PlaybackRecoveryConfig = {
+  enabled: boolean;
+  stallTimeoutMs: number;
+  maxRetries: number;
+  logToConsole: boolean;
+};
+
+export default createPlugin<
+  unknown,
+  unknown,
+  {
+    config: PlaybackRecoveryConfig | null;
+    api: MusicPlayer | null;
+    watchdog: ReturnType<typeof setInterval> | null;
+    videoObserver: MutationObserver | null;
+    consecutiveFailures: number;
+    lastGoodTime: number;
+    lastGoodTimestamp: number;
+    recovering: boolean;
+  },
+  PlaybackRecoveryConfig
+>({
+  name: () => t('plugins.playback-recovery.name'),
+  description: () => t('plugins.playback-recovery.description'),
+  restartNeeded: false,
+  config: {
+    enabled: false,
+    stallTimeoutMs: 8000,
+    maxRetries: 5,
+    logToConsole: true,
+  },
+  menu: async ({ getConfig, setConfig }) => {
+    const config = await getConfig();
+
+    return [
+      {
+        label: t('plugins.playback-recovery.menu.log-to-console'),
+        type: 'checkbox',
+        checked: config.logToConsole,
+        async click() {
+          const nowConfig = await getConfig();
+          setConfig({ logToConsole: !nowConfig.logToConsole });
+        },
+      },
+    ];
+  },
+  renderer: {
+    config: null,
+    api: null,
+    watchdog: null,
+    videoObserver: null,
+    consecutiveFailures: 0,
+    lastGoodTime: 0,
+    lastGoodTimestamp: 0,
+    recovering: false,
+
+    async start({ getConfig }) {
+      this.config = await getConfig();
+    },
+
+    onPlayerApiReady(api) {
+      this.api = api;
+      this.log('Playback recovery active');
+      this.startWatchdog();
+      this.watchVideoElement();
+      this.hookMediaEvents();
+    },
+
+    stop() {
+      if (this.watchdog) {
+        clearInterval(this.watchdog);
+        this.watchdog = null;
+      }
+      if (this.videoObserver) {
+        this.videoObserver.disconnect();
+        this.videoObserver = null;
+      }
+    },
+
+    onConfigChange(newConfig) {
+      this.config = newConfig;
+    },
+
+    // --- Internal methods attached as properties ---
+
+    log(msg: string) {
+      if (this.config?.logToConsole) {
+        console.log(`[playback-recovery] ${msg}`);
+      }
+    },
+
+    getVideo(): HTMLVideoElement | null {
+      return document.querySelector('video');
+    },
+
+    hookMediaEvents() {
+      const attachTo = (video: HTMLVideoElement) => {
+        if ((video as any).__pbRecovery) return;
+        (video as any).__pbRecovery = true;
+
+        // Track healthy playback progress
+        video.addEventListener('timeupdate', () => {
+          if (video.currentTime > 0 && !video.paused) {
+            this.lastGoodTime = video.currentTime;
+            this.lastGoodTimestamp = Date.now();
+            this.consecutiveFailures = 0;
+            this.recovering = false;
+          }
+        });
+
+        // On error, attempt immediate recovery
+        video.addEventListener('error', () => {
+          const code = video.error?.code ?? 0;
+          const msg = video.error?.message ?? '';
+          this.log(`Media error: code=${code} msg="${msg}"`);
+          this.attemptRecovery('media-error');
+        });
+
+        // On stall, start a short timer — if it doesn't resolve, recover
+        video.addEventListener('stalled', () => {
+          this.log('Stream stalled, waiting for recovery...');
+          setTimeout(() => {
+            const v = this.getVideo();
+            if (v && !v.paused && v.readyState < 3) {
+              this.log('Stall did not resolve');
+              this.attemptRecovery('stall-timeout');
+            }
+          }, this.config?.stallTimeoutMs ?? 8000);
+        });
+
+        // On waiting (buffering), monitor if it persists too long
+        video.addEventListener('waiting', () => {
+          setTimeout(() => {
+            const v = this.getVideo();
+            if (v && !v.paused && v.readyState < 2) {
+              this.log('Buffering did not resolve');
+              this.attemptRecovery('buffer-timeout');
+            }
+          }, this.config?.stallTimeoutMs ?? 8000);
+        });
+      };
+
+      const video = this.getVideo();
+      if (video) attachTo(video);
+
+      // Also re-attach on video element recreation (MutationObserver in watchVideoElement handles this)
+      (this as any)._attachMediaEvents = attachTo;
+    },
+
+    watchVideoElement() {
+      // Watch for video element being destroyed and recreated
+      this.videoObserver = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          for (const node of mutation.removedNodes) {
+            if (
+              node instanceof HTMLElement &&
+              (node.tagName === 'VIDEO' || node.tagName === 'AUDIO')
+            ) {
+              this.log('Video element removed from DOM');
+            }
+          }
+          for (const node of mutation.addedNodes) {
+            if (node instanceof HTMLVideoElement) {
+              this.log('New video element detected — re-attaching recovery hooks');
+              (this as any)._attachMediaEvents?.(node);
+            }
+          }
+        }
+      });
+      this.videoObserver.observe(document.body, {
+        childList: true,
+        subtree: true,
+      });
+    },
+
+    startWatchdog() {
+      // Core watchdog: every 3 seconds, check if playback is healthy
+      this.watchdog = setInterval(() => {
+        if (this.recovering) return;
+
+        const video = this.getVideo();
+        if (!video) return;
+
+        // Only check if the player thinks it's playing
+        const playerState = this.api?.getPlayerState?.();
+        const isPlaying = playerState === 1; // 1 = playing
+        if (!isPlaying) return;
+
+        const now = Date.now();
+
+        // Case 1: readyState 0 while "playing" — completely stuck
+        if (video.readyState === 0 && !video.paused) {
+          const elapsed = now - this.lastGoodTimestamp;
+          if (elapsed > (this.config?.stallTimeoutMs ?? 8000)) {
+            this.log(
+              `Dead playback: readyState=0, no progress for ${elapsed}ms`,
+            );
+            this.attemptRecovery('dead-playback');
+            return;
+          }
+        }
+
+        // Case 2: currentTime not advancing while not paused
+        if (!video.paused && video.currentTime > 0) {
+          const timeSinceGood = now - this.lastGoodTimestamp;
+          if (
+            timeSinceGood > (this.config?.stallTimeoutMs ?? 8000) &&
+            this.lastGoodTimestamp > 0
+          ) {
+            this.log(
+              `Playback frozen: currentTime=${video.currentTime.toFixed(1)}, no progress for ${timeSinceGood}ms`,
+            );
+            this.attemptRecovery('frozen-playback');
+            return;
+          }
+        }
+
+        // Case 3: buffered data exhausted while playing
+        if (!video.paused && video.buffered.length > 0) {
+          const bufferEnd = video.buffered.end(video.buffered.length - 1);
+          const ahead = bufferEnd - video.currentTime;
+          if (ahead <= 0 && video.readyState < 3) {
+            this.log(`Buffer exhausted: ahead=${ahead.toFixed(1)}s, readyState=${video.readyState}`);
+            this.attemptRecovery('buffer-exhausted');
+          }
+        }
+      }, 3000);
+    },
+
+    attemptRecovery(reason: string) {
+      if (this.recovering) return;
+
+      const maxRetries = this.config?.maxRetries ?? 5;
+      this.consecutiveFailures++;
+
+      if (this.consecutiveFailures > maxRetries) {
+        this.log(
+          `Max retries (${maxRetries}) exceeded — skipping to next track`,
+        );
+        this.recovering = true;
+        this.consecutiveFailures = 0;
+        try {
+          this.api?.nextVideo();
+          this.log('Skipped to next track');
+        } catch (e) {
+          this.log('Failed to skip: ' + String(e));
+        }
+        // Give the next track time to load before watchdog kicks in
+        setTimeout(() => {
+          this.recovering = false;
+          this.lastGoodTimestamp = Date.now();
+        }, 5000);
+        return;
+      }
+
+      this.log(
+        `Recovery attempt ${this.consecutiveFailures}/${maxRetries} — reason: ${reason}`,
+      );
+      this.recovering = true;
+
+      const video = this.getVideo();
+      const currentTime = video?.currentTime ?? 0;
+
+      // Strategy 1: Try seeking to current position (forces buffer reload)
+      if (this.consecutiveFailures <= 2) {
+        this.log('Strategy: seek-to-current');
+        try {
+          if (this.api && currentTime > 0) {
+            this.api.seekTo(currentTime);
+            this.api.playVideo();
+          } else if (this.api) {
+            this.api.playVideo();
+          }
+        } catch (e) {
+          this.log('Seek failed: ' + String(e));
+        }
+      }
+      // Strategy 2: Reload the video by seeking slightly forward
+      else if (this.consecutiveFailures <= 4) {
+        this.log('Strategy: seek-forward');
+        try {
+          if (this.api && currentTime > 0) {
+            this.api.seekTo(currentTime + 1);
+            this.api.playVideo();
+          } else if (this.api) {
+            // If currentTime is 0, try loading the video data fresh
+            this.api.playVideo();
+          }
+        } catch (e) {
+          this.log('Seek-forward failed: ' + String(e));
+        }
+      }
+
+      // Allow recovery to settle before checking again
+      setTimeout(() => {
+        this.recovering = false;
+        this.lastGoodTimestamp = Date.now();
+      }, 4000);
+    },
+  },
+});
diff --git a/src/tray.ts b/src/tray.ts
index 89f13eba8f..f44f101874 100644
--- a/src/tray.ts
+++ b/src/tray.ts
@@ -11,6 +11,7 @@ import * as config from './config';
 import { restart } from './providers/app-controls';
 import { registerCallback, SongInfoEvent } from './providers/song-info';
 import { getSongControls } from './providers/song-controls';
+import { showOnCurrentDesktop } from './window-utils';
 
 import { APPLICATION_NAME, t } from '@/i18n';
 
@@ -24,8 +25,20 @@ type TrayEvent = (
   bounds: Electron.Rectangle,
 ) => void;
 
+type MouseMoveEvent = (
+  event: Electron.KeyboardEvent,
+  position: Electron.Point,
+) => void;
+
+// Plugins load before the tray is created, so queue handlers
+// registered early and apply them once setUpTray runs.
+let pendingClick: TrayEvent | null = null;
+let pendingDoubleClick: TrayEvent | null = null;
+let pendingMouseMove: MouseMoveEvent | null = null;
+
 export const setTrayOnClick = (fn: TrayEvent) => {
   if (!tray) {
+    pendingClick = fn;
     return;
   }
 
@@ -36,6 +49,7 @@ export const setTrayOnClick = (fn: TrayEvent) => {
 // Won't do anything on macOS since its disabled
 export const setTrayOnDoubleClick = (fn: TrayEvent) => {
   if (!tray) {
+    pendingDoubleClick = fn;
     return;
   }
 
@@ -43,6 +57,19 @@ export const setTrayOnDoubleClick = (fn: TrayEvent) => {
   tray.on('double-click', fn);
 };
 
+// macOS and Windows only
+export const setTrayOnMouseMove = (fn: MouseMoveEvent) => {
+  if (!tray) {
+    pendingMouseMove = fn;
+    return;
+  }
+
+  tray.removeAllListeners('mouse-move');
+  tray.on('mouse-move', fn);
+};
+
+export const getTrayBounds = () => tray?.getBounds();
+
 export const setUpTray = (app: Electron.App, win: Electron.BrowserWindow) => {
   if (!config.get('options.tray')) {
     tray = undefined;
@@ -86,7 +113,11 @@ export const setUpTray = (app: Electron.App, win: Electron.BrowserWindow) => {
       win.hide();
       app.dock?.hide();
     } else {
-      win.show();
+      if (config.get('options.trayMoveToCurrentDesktop')) {
+        showOnCurrentDesktop(win);
+      } else {
+        win.show();
+      }
       app.dock?.show();
     }
   });
@@ -113,7 +144,11 @@ export const setUpTray = (app: Electron.App, win: Electron.BrowserWindow) => {
     {
       label: t('main.tray.show'),
       click() {
-        win.show();
+        if (config.get('options.trayMoveToCurrentDesktop')) {
+          showOnCurrentDesktop(win);
+        } else {
+          win.show();
+        }
         app.dock?.show();
       },
     },
@@ -152,4 +187,22 @@ export const setUpTray = (app: Electron.App, win: Electron.BrowserWindow) => {
       tray.setImage(songInfo.isPaused ? pausedTrayIcon : defaultTrayIcon);
     }
   });
+
+  // Apply any handlers that plugins registered before the tray existed
+  if (pendingClick) {
+    tray.removeAllListeners('click');
+    tray.on('click', pendingClick);
+    pendingClick = null;
+  }
+
+  if (pendingDoubleClick) {
+    tray.removeAllListeners('double-click');
+    tray.on('double-click', pendingDoubleClick);
+    pendingDoubleClick = null;
+  }
+
+  if (pendingMouseMove) {
+    tray.on('mouse-move', pendingMouseMove);
+    pendingMouseMove = null;
+  }
 };
diff --git a/src/window-utils.ts b/src/window-utils.ts
new file mode 100644
index 0000000000..f6e337d672
--- /dev/null
+++ b/src/window-utils.ts
@@ -0,0 +1,12 @@
+/**
+ * Shows a window on the current virtual desktop instead of switching
+ * to the desktop where the window was originally created.
+ *
+ * Works by temporarily pinning the window to all workspaces,
+ * then unpinning it — leaving it on the current one.
+ */
+export const showOnCurrentDesktop = (win: Electron.BrowserWindow) => {
+  win.setVisibleOnAllWorkspaces(true);
+  win.show();
+  win.setVisibleOnAllWorkspaces(false);
+};

From f4b1f37a7443efa79f699c60085ae6211b3f5942 Mon Sep 17 00:00:00 2001
From: EmreSoyak <emresoyak@gmail.com>
Date: Wed, 15 Apr 2026 19:01:15 +0300
Subject: [PATCH 2/2] docs: Rewrite feature documentation for upstream
 readability

Rewrites EMRE-FEATURES.md with focus on user problems and benefits
rather than implementation notes. Each feature section now explains
the pain point it solves, how the solution works, and what files
are involved. Updated hover popup docs to reflect the final
implementation (cursor polling, title-based IPC).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 EMRE-FEATURES.md | 360 +++++++++++++++++------------------------------
 1 file changed, 128 insertions(+), 232 deletions(-)

diff --git a/EMRE-FEATURES.md b/EMRE-FEATURES.md
index 6e1d89b183..d6ce98e89c 100644
--- a/EMRE-FEATURES.md
+++ b/EMRE-FEATURES.md
@@ -1,307 +1,203 @@
-# Emre's YouTube Music Player - Custom Features
+# Feature Pack: Desktop Workflow Enhancements
 
-A collection of custom features and enhancements for [th-ch/youtube-music](https://github.com/th-ch/youtube-music), focused on virtual desktop workflows, memory optimization, playback reliability, and tray UX improvements.
+A set of four opt-in features for power users who run YouTube Music as a background audio companion on desktop — particularly those who use virtual desktops, minimize to tray, and want quick playback control without opening the full window.
 
----
-
-## Table of Contents
-
-1. [Audio-Only Mode](#1-audio-only-mode) (Plugin)
-2. [Playback Recovery](#2-playback-recovery) (Plugin)
-3. [Virtual Desktop Awareness](#3-virtual-desktop-awareness) (Core setting)
-4. [Tray Hover Mini-Player](#4-tray-hover-mini-player) (Notification plugin extension)
-5. [DevTools Control](#5-devtools-control) (Core tweak)
-6. [Diagnostic Tools](#6-diagnostic-tools) (External scripts)
-7. [Build & Launch Scripts](#7-build--launch-scripts)
+Every feature defaults to **off** and is toggled from the existing settings/plugin menu. No existing behavior is changed unless the user explicitly enables a feature.
 
 ---
 
 ## 1. Audio-Only Mode
 
-**Type:** Plugin
-**Location:** `src/plugins/audio-only/index.ts`
-**Toggle:** Settings > Plugins > Audio Only (requires restart)
-**Default:** Off
+**Plugin** | Settings > Plugins > Audio Only | Requires restart
+
+### The problem
 
-### What it does
+YouTube Music streams video even when the window is minimized or hidden in the tray. On a desktop app used purely for music, this wastes ~300 MB of RAM on video decoding and buffering that nobody is watching.
 
-Forces YouTube Music to stream audio only, eliminating video decoding and buffering entirely. This cuts memory usage by roughly 300+ MB.
+### The solution
+
+A renderer plugin that forces YouTube Music into its audio-only playback path — the same mode the mobile app uses on audio-only plans. Video decoding stops entirely, album art is shown instead, and memory usage drops significantly.
 
 ### How it works
 
-1. Sets `playback-mode="ATV_PREFERRED"` on the `ytmusic-player` element (tells YouTube this is an audio-only device)
-2. Calls `moviePlayer.setPlaybackQuality('tiny')` and `setPlaybackQualityRange('tiny')` via the internal player API
-3. Hides the `<video>` element and the `#song-video` container, forces album art (`#song-image`) visible
-4. Uses a `MutationObserver` to lock the `playback-mode` attribute — YouTube periodically tries to flip it back to `OMV_PREFERRED`; this prevents that
-5. Re-applies on every song change via the `videodatachange` event
+- Sets `playback-mode="ATV_PREFERRED"` on the player element, telling YouTube's player this is an audio-only surface
+- Calls `setPlaybackQuality('tiny')` via the internal player API to prevent video stream selection
+- Hides the `<video>` element and shows album art (`#song-image`) instead
+- A `MutationObserver` locks the `playback-mode` attribute — YouTube periodically tries to flip it back to video mode; this prevents that
+- Re-applies on every song change via the `videodatachange` event
 
-### Config
+### Files
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | boolean | `false` | Enable audio-only mode |
+| File | Role |
+|------|------|
+| `src/plugins/audio-only/index.ts` | Full plugin (renderer-side) |
 
 ---
 
 ## 2. Playback Recovery
 
-**Type:** Plugin
-**Location:** `src/plugins/playback-recovery/index.ts`
-**Toggle:** Settings > Plugins > Playback Recovery
-**Default:** Off
+**Plugin** | Settings > Plugins > Playback Recovery
 
-### What it does
+### The problem
 
-Automatically detects and recovers from stuck, stalled, or dead playback states. When YouTube Music's player freezes (which happens regularly), this plugin intervenes without user action.
+YouTube Music's web player occasionally enters a stuck state — the progress bar stops, audio cuts out, but the UI still shows "playing." This happens more frequently during long listening sessions, on flaky connections, or after the system wakes from sleep. The only fix is to manually skip the track or reload the app.
 
-### How it works
+### The solution
 
-**Watchdog (runs every 3 seconds):**
-- Checks if `readyState === 0` while the player reports "playing" (completely dead)
-- Checks if `currentTime` hasn't advanced while not paused (frozen playback)
-- Checks if buffered data is exhausted while playing
+A watchdog plugin that monitors the `<video>` element's health every 3 seconds and applies progressive recovery strategies when playback stalls. It handles dead playback, frozen progress, buffer exhaustion, media errors, and stream stalls — all without user intervention.
 
-**Media event hooks:**
-- `error` — immediate recovery attempt on media errors
-- `stalled` — waits for the stall timeout, then recovers if unresolved
-- `waiting` — monitors if buffering persists too long
-- `timeupdate` — tracks healthy playback (resets failure counters)
+### How it works
+
+**Detection (watchdog runs every 3 seconds):**
 
-**MutationObserver:**
-- Watches for the `<video>` element being removed and recreated by YouTube's player
-- Re-attaches recovery hooks to the new element automatically
+| Condition | Meaning |
+|-----------|---------|
+| `readyState === 0` while player state is "playing" | Completely dead — no media data loaded |
+| `currentTime` not advancing while not paused | Frozen — player thinks it's playing but nothing moves |
+| Buffer end <= current time while `readyState < 3` | Buffer exhausted — nothing left to play |
 
 **Recovery strategies (progressive):**
-1. **Seek to current position** (attempts 1-2) — forces buffer reload
-2. **Seek forward 1 second** (attempts 3-4) — gets past potentially corrupt segments
-3. **Skip to next track** (after max retries) — gives up on the current song
+
+| Attempt | Strategy | What it does |
+|---------|----------|-------------|
+| 1-2 | Seek to current position | Forces the player to re-request the current buffer segment |
+| 3-4 | Seek forward 1 second | Jumps past a potentially corrupt segment |
+| 5+ | Skip to next track | Gives up on the current song and moves on |
+
+**Event hooks:** Also listens for `error`, `stalled`, and `waiting` events for immediate detection. A `MutationObserver` watches for the `<video>` element being destroyed and recreated by YouTube's player, automatically re-attaching hooks to the new element.
 
 ### Config
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | boolean | `false` | Enable playback recovery |
-| `stallTimeoutMs` | number | `8000` | Milliseconds before a stall triggers recovery |
-| `maxRetries` | number | `5` | Max recovery attempts before skipping the track |
-| `logToConsole` | boolean | `true` | Log recovery events to the DevTools console |
+| Option | Default | Description |
+|--------|---------|-------------|
+| `stallTimeoutMs` | `8000` | How long to wait before a stall triggers recovery |
+| `maxRetries` | `5` | Max recovery attempts before skipping to next track |
+| `logToConsole` | `true` | Log recovery events to DevTools console for debugging |
 
-### Menu
+### Files
 
-- **Log recovery events to console** (checkbox) — under the plugin's settings
+| File | Role |
+|------|------|
+| `src/plugins/playback-recovery/index.ts` | Full plugin (renderer-side, watchdog + event hooks) |
 
 ---
 
 ## 3. Virtual Desktop Awareness
 
-**Type:** Core setting (not a plugin)
-**Location:** `src/window-utils.ts`, `src/tray.ts`, `src/index.ts`
-**Toggle:** Options > Tray > "Move to current virtual desktop on show"
-**Default:** Off
-
-### What it does
+**Core setting** | Options > Tray > "Move to current virtual desktop on show"
 
-When enabled, clicking the tray icon (or launching a second instance) **moves the YouTube Music window to your current virtual desktop** instead of yanking you back to the desktop where the window originally opened.
+### The problem
 
-### How it works
+On Windows 10/11 (and macOS/Linux with workspaces), if YouTube Music is open on Desktop 1 and you're working on Desktop 3, clicking the tray icon or launching a second instance **yanks you back to Desktop 1** instead of bringing the window to you. This breaks the flow for anyone who uses virtual desktops to organize their work.
 
-Uses Electron's `setVisibleOnAllWorkspaces` API:
-1. `win.setVisibleOnAllWorkspaces(true)` — temporarily pins the window to all desktops (makes it appear on the current one)
-2. `win.show()` — shows and focuses the window
-3. `win.setVisibleOnAllWorkspaces(false)` — unpins it, leaving it on the current desktop
+### The solution
 
-**Applied at 3 call sites:**
-- Tray icon single-click (show window)
-- Tray right-click menu > "Show"
-- Second-instance handler (when you double-click the app shortcut while it's already running)
-
-### Config
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `options.trayMoveToCurrentDesktop` | boolean | `false` | Move window to current virtual desktop on show |
-
----
-
-## 4. Tray Hover Mini-Player
-
-**Type:** Notification plugin extension
-**Location:** `src/plugins/notifications/hover-popup.ts`, `assets/hover-popup.html`
-**Toggle:** Notifications plugin > Interactive Settings > "Show mini-player on tray hover"
-**Default:** Off
-**Prerequisite:** Notifications plugin must be enabled
-
-### What it does
-
-When you hover over the YouTube Music tray icon, a compact floating mini-player appears showing the current song's album art, title, artist, and playback controls (previous / play-pause / next). The popup stays visible as long as your mouse is on the tray icon or on the popup itself, then fades out when you move away.
-
-This solves the problem of YouTube Music's native toast notifications disappearing after 5 seconds before you can interact with them.
+When this setting is enabled, showing the YouTube Music window — whether by tray click, the "Show" context menu, or launching a second instance — **moves the window to your current desktop** instead of switching desktops.
 
 ### How it works
 
-**Popup window:**
-- Frameless, transparent, always-on-top `BrowserWindow` (380x85 content area)
-- Dark theme matching YouTube Music's aesthetic (#282828 background)
-- Positioned above the tray icon, centered
-- Uses `setIgnoreMouseEvents(true, { forward: true })` for transparent areas (click-through) and toggles to `setIgnoreMouseEvents(false)` when mouse enters the popup card
-
-**Hover tracking:**
-- `tray.on('mouse-move')` detects when the cursor is over the tray icon
-- When `mouse-move` stops firing for 300ms, the tray is considered "left"
-- The popup's HTML tracks `mouseenter`/`mouseleave` on the card itself
-- A 400ms grace period allows moving between tray and popup without dismissing
-- Communication between HTML and main process uses `console.log('__IPC__:...')` messages intercepted via `webContents.on('console-message')`
-
-**Song info:**
-- Registers its own `registerCallback` for song change events
-- Pushes updates to the popup via `webContents.executeJavaScript()`
+Uses Electron's `setVisibleOnAllWorkspaces` API with a pin/unpin technique:
 
-### Config
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `hoverControls` | boolean | `false` | Show mini-player popup on tray hover |
-
----
-
-## 5. DevTools Control
-
-**Type:** Core tweak
-**Location:** `src/index.ts` (line ~315)
-**Toggle:** Environment variable `OPEN_DEVTOOLS=1`
-**Default:** DevTools do NOT auto-open in dev mode
+```
+win.setVisibleOnAllWorkspaces(true)   // Pin to all desktops (appears on current)
+win.show()                             // Show and focus
+win.setVisibleOnAllWorkspaces(false)  // Unpin (stays on current desktop)
+```
 
-### What it does
+Applied at all 3 places where the window is shown:
+1. Tray icon click (show window)
+2. Tray right-click > "Show" menu item
+3. Second-instance handler (launching the app while it's already running)
 
-By default in the upstream repo, DevTools auto-open whenever you run in dev mode. This change gates that behind an environment variable so DevTools only open when explicitly requested.
+Cross-platform: works on Windows virtual desktops, macOS Spaces, and Linux workspaces.
 
-### How to use
+### Files
 
-- **Normal dev mode:** `pnpm dev` — DevTools stay closed
-- **With DevTools:** `OPEN_DEVTOOLS=1 pnpm dev`
-- **Manual toggle:** Press `Ctrl+Shift+I` at any time in the running app
+| File | Role |
+|------|------|
+| `src/window-utils.ts` | `showOnCurrentDesktop()` helper (new file) |
+| `src/tray.ts` | Uses helper in click + "Show" menu handlers |
+| `src/index.ts` | Uses helper in second-instance handler |
+| `src/config/defaults.ts` | `trayMoveToCurrentDesktop` option |
+| `src/menu.ts` | Toggle in Options > Tray submenu |
 
 ---
 
-## 6. Diagnostic Tools
-
-External scripts for debugging playback issues without modifying the app's source code. These connect via Chrome DevTools Protocol (CDP) when the app is launched with `--remote-debugging-port=9222`.
-
-### monitor.cjs
-
-**Location:** `monitor.cjs` (root)
-**Purpose:** Real-time playback diagnostics
-
-Connects to the running app via CDP and monitors:
-- All media events (play, pause, error, stalled, waiting, ended, etc.)
-- Flicker detection (rapid play/pause cycling)
-- Video element recreation
-- "Are you still listening?" popup detection
-- Network failures on media resources
-- ReadyState drops and buffer exhaustion
-
-Output is color-coded with tags: `INFO`, `PLAY`, `PAUSE`, `WARN`, `ERROR`, `EVENT`, `DIALOG`, `NET`, `CONSOLE`.
-
-**Usage:** `node monitor.cjs` (while app runs with debug port)
-
-### inject-lightweight.cjs
+## 4. Tray Hover Mini-Player
 
-**Location:** `inject-lightweight.cjs` (root)
-**Purpose:** Runtime audio-only injection (non-permanent alternative to the Audio-Only plugin)
+**Notification plugin extension** | Interactive Settings > "Show mini-player on tray hover"
 
-Injects via CDP to:
-1. Block 68+ video stream URLs (itag 13-702) from googlevideo.com using `Network.setBlockedURLs`
-2. Intercept `fetch()` calls and return 204 for video MIME types
-3. Force `playback-mode="ATV_PREFERRED"`
-4. Hide video element, show album art
-5. Run periodic buffer monitoring (logs every 30s)
+### The problem
 
-**Usage:** `node inject-lightweight.cjs` (while app runs with debug port)
+The existing interactive toast notification shows song info and controls when a song changes, but it auto-dismisses after 5 seconds. If you miss it or want to skip a track 30 seconds later, your only options are:
 
-> **Note:** The Audio-Only plugin (feature #1) is the permanent, built-in version of this. Use `inject-lightweight.cjs` only for one-off testing without rebuilding.
+- **Double-click the tray icon** — opens the full window (overkill for just pressing "next")
+- **Right-click the tray** — opens a basic text menu (functional but no album art, no visual feedback)
 
----
+There's no quick, on-demand way to see what's playing and control it without opening the full app.
 
-## 7. Build & Launch Scripts
+### The solution
 
-### build.bat
+Hovering over the tray icon shows a compact floating mini-player with album art, song title, artist, and previous/play-pause/next buttons. It stays visible as long as your mouse is on the tray icon or the popup, and fades out when you move away.
 
-**Location:** `build.bat` (root)
+This gives users three tiers of tray interaction:
+1. **Hover** — Quick glance + controls via the mini-player
+2. **Single click** — Toggle the toast notification (existing behavior)
+3. **Double click** — Open the full window (existing behavior)
 
-One-click rebuild: `pnpm clean` > `pnpm build` > `pnpm electron-builder --win dir:x64 -p never`
+### How it works
 
-Output: `pack\win-unpacked\YouTube Music.exe`
+**Popup window:**
+- Frameless, transparent, always-on-top `BrowserWindow` positioned above the tray icon
+- Dark theme (#282828) matching YouTube Music's aesthetic
+- Shows album art (56x56), song title, artist, and SVG icon buttons
 
-### start.bat
+**Hover tracking (main process cursor polling):**
+- `tray.on('mouse-move')` triggers the popup to appear
+- A 150ms `setInterval` polls `screen.getCursorScreenPoint()` and checks if the cursor is over the popup bounds or the tray icon bounds
+- If the cursor is on neither for a full cycle, the popup fades out
+- This approach is more reliable on Windows than HTML-based mouseenter/mouseleave events
 
-**Location:** `start.bat` (root)
+**Button clicks (`document.title` IPC):**
+- Buttons use `onmousedown` (fires before window activation) and set `document.title` to signal the action
+- Main process listens via `BrowserWindow.on('page-title-updated')` — reliable regardless of window focus state
+- A counter is appended to ensure repeated clicks on the same button always trigger
 
-Launches the built exe from `pack\win-unpacked\YouTube Music.exe`.
+**Toast suppression:**
+- When the hover popup is visible, the interactive toast notification is suppressed to prevent both from appearing simultaneously
+- The popup exports `isHoverPopupVisible()` which `interactive.ts` checks before showing a toast
 
-### diagnose.bat
+### Infrastructure fix: Deferred tray event handlers
 
-**Location:** `diagnose.bat` (root)
+Plugins load (`loadAllMainPlugins`) before the tray is created (`setUpTray`). Any `setTrayOnClick`, `setTrayOnDoubleClick`, or `setTrayOnMouseMove` calls from plugins were silently dropped because the tray didn't exist yet.
 
-Launches the app with `--remote-debugging-port=9222` and starts `monitor.cjs` for live playback diagnostics.
+Fixed by queuing handlers registered before the tray exists and applying them at the end of `setUpTray`. This fix also benefits the existing notification plugin's `trayControls` feature, which had the same latent timing bug.
 
-### Icon & Shortcut Scripts
+### Files
 
-| Script | Purpose |
-|--------|---------|
-| `make-icon.ps1` | Converts `assets/icon.png` to `icon.ico` (multi-size) |
-| `update-shortcut.ps1` | Creates/updates desktop shortcut pointing to the built exe with the custom icon |
-| `pin-shortcut.ps1` | Old dev-mode shortcut script (obsolete) |
+| File | Role |
+|------|------|
+| `src/plugins/notifications/hover-popup.ts` | Popup window management, cursor tracking, IPC (new file) |
+| `assets/hover-popup.html` | Mini-player UI: HTML, CSS, button handlers (new file) |
+| `src/plugins/notifications/index.ts` | `hoverControls` config option |
+| `src/plugins/notifications/main.ts` | Wires up `setupHoverPopup()` |
+| `src/plugins/notifications/menu.ts` | Menu toggle |
+| `src/plugins/notifications/interactive.ts` | Toast suppression check |
+| `src/tray.ts` | `setTrayOnMouseMove()`, `getTrayBounds()`, deferred handler queue |
 
 ---
 
-## File Map
-
-All custom files at a glance:
-
-```
-z_youtube_player/
-  EMRE-FEATURES.md              <- This file
-  build.bat                      <- Build script
-  start.bat                      <- Launch script
-  diagnose.bat                   <- Debug launcher
-  monitor.cjs                    <- CDP playback monitor
-  inject-lightweight.cjs         <- CDP audio-only injector
-  icon.ico                       <- Custom app icon
-  make-icon.ps1                  <- Icon generator
-  update-shortcut.ps1            <- Shortcut updater
-  pin-shortcut.ps1               <- (obsolete)
-  assets/
-    hover-popup.html             <- Tray hover mini-player UI
-  src/
-    window-utils.ts              <- Virtual desktop helper
-    plugins/
-      audio-only/
-        index.ts                 <- Audio-Only plugin
-      playback-recovery/
-        index.ts                 <- Playback Recovery plugin
-      notifications/
-        hover-popup.ts           <- Tray hover mini-player logic
-  Modified core files:
-    src/index.ts                 <- DevTools gate + virtual desktop
-    src/tray.ts                  <- Virtual desktop + mouse-move support
-    src/config/defaults.ts       <- trayMoveToCurrentDesktop option
-    src/menu.ts                  <- Virtual desktop menu item
-    src/i18n/resources/en.json   <- All new labels
-    src/plugins/notifications/
-      index.ts                   <- hoverControls config
-      main.ts                    <- Hover popup wiring
-      menu.ts                    <- Hover controls menu item
-```
+## Summary
 
----
+| Feature | Type | Toggle | Default | Platform |
+|---------|------|--------|---------|----------|
+| Audio-Only Mode | Plugin | Plugin settings | Off | All |
+| Playback Recovery | Plugin | Plugin settings | Off | All |
+| Virtual Desktop Awareness | Core setting | Options > Tray | Off | Windows, macOS, Linux |
+| Tray Hover Mini-Player | Plugin extension | Notifications > Interactive Settings | Off | Windows, macOS |
 
-## Feature Status Summary
-
-| # | Feature | Type | Toggle | Default |
-|---|---------|------|--------|---------|
-| 1 | Audio-Only Mode | Plugin | Plugin settings | Off |
-| 2 | Playback Recovery | Plugin | Plugin settings | Off |
-| 3 | Virtual Desktop Awareness | Core setting | Options > Tray | Off |
-| 4 | Tray Hover Mini-Player | Plugin extension | Notifications > Interactive Settings | Off |
-| 5 | DevTools Control | Core tweak | `OPEN_DEVTOOLS=1` env var | Off |
-| 6 | Diagnostic Tools | External scripts | Run manually | N/A |
-| 7 | Build Scripts | External scripts | Run manually | N/A |
+All features are:
+- **Opt-in** — disabled by default, no impact on existing users
+- **Independent** — can be enabled in any combination
+- **Consistent** — follow existing plugin/config/menu/i18n patterns
+- **Reversible** — toggle off and restart to fully revert