From 0dc3a220d95b4b7264f76bc50f3cfc6050d58f07 Mon Sep 17 00:00:00 2001
From: David Keane <david.keane.1974@gmail.com>
Date: Sat, 30 May 2026 00:03:21 +0100
Subject: [PATCH] =?UTF-8?q?feat(0.6.0):=20pop-out=20mini-player=20?=
 =?UTF-8?q?=E2=80=94=20continuous=20background=20play=20across=20admin=20n?=
 =?UTF-8?q?av?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Until v0.5.0 the audio cut every time you navigated between WP admin
pages — every navigation is a full page reload, which destroys the
<audio> element. v0.6.0 fixes the background-music use case by letting
you pop the player out into a separate browser window that persists
across the parent tab's navigation.

Pop-out window
  - Small "↗ Pop out" button beside the Play button on both the main
    Radio page and the Dashboard widget.
  - Opens a 380×560 standalone window via window.open() with a window
    name of `radio_popout` so a second click re-focuses the existing
    popup rather than spawning a new one.
  - Popup renders at admin-post.php?action=radio_popout&play=1 — a new
    admin_post_radio_popout hook outputs a full standalone HTML page
    (custom DOCTYPE / head / body, no WP admin chrome).
  - Theme follows radio_state['theme'] via body class radio-theme-{...}.
  - Includes the full player (now-playing block with dancing bars +
    Web Audio visualizer, play, mute, volume, station dropdown, error
    slot). Close button calls window.close().

Auto-resume + single-stream invariant
  - cfg.autoPlay is true when the popup URL carries &play=1. radio.js
    auto-calls audio.play() 200 ms after init. Same-origin user-gesture
    popups are exempt from autoplay-blocking on every modern browser.
  - On pop-out click, every other audio surface in the parent tab is
    paused so there is only ever one stream playing.

State stays in sync
  - Popup uses the SAME radio_save_state AJAX + track-logging endpoint.
    Station / volume changes persist to user_meta; track history keeps
    accumulating from whichever surface is playing.

Edge cases
  - Inside the popup, cfg.popoutUrl is '' so bindPopOut hides any
    Pop-out button it finds (would be infinite otherwise).
  - Popup blocked by browser → clear alert tells the user to allow
    popups for this site.

Files
  - radio.php (version, popoutUrl in localized config, admin_post
    handler + full standalone HTML renderer)
  - inc/admin-page.php + inc/dashboard-widget.php (Pop-out button
    beside Play)
  - assets/css/radio.css (.radio-player__popout styling)
  - assets/js/radio.js (bindPopOut function; autoPlay branch in
    bindPlayer)
  - inc/about.php + CHANGELOG.md (history entries)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md             |  29 ++++++++
 assets/css/radio.css     |  10 +++
 assets/js/radio.js       |  38 +++++++++++
 inc/about.php            |   6 +-
 inc/admin-page.php       |   4 ++
 inc/dashboard-widget.php |   4 ++
 radio.php                | 138 ++++++++++++++++++++++++++++++++++++++-
 7 files changed, 226 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 90c2c6c..6903826 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,35 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) — versi
 
 ---
 
+## [0.6.0] — 2026-05-30 — Pop-out mini-player (continuous background play)
+
+Until v0.5.0 the audio cut every time you navigated between WP admin pages — every navigation is a full page reload, which destroys the `<audio>` element. v0.6.0 fixes the background-music use case by letting you pop the player out into a separate browser window that persists across the parent tab's navigation.
+
+### Added — **Pop out** button + standalone popup player
+- Small **`↗ Pop out`** button beside the Play button on both the main Radio page and the Dashboard widget. Click it and a **380×560 standalone window** opens with just the player chrome (no WP admin sidebar / nav).
+- The popup lives at `admin-post.php?action=radio_popout&play=1` — a new server-side route that renders a **full standalone HTML page** outside the WP admin shell (custom `<!DOCTYPE>`, head, body, no admin chrome).
+- Popup is `radio_popout`-named so a second click on Pop out **re-focuses the existing window** instead of opening a new one.
+- The popup's `<audio>` element is never destroyed by parent-tab navigation, so the music keeps playing while you click around Plugins, Posts, Users, etc.
+
+### Auto-resume — pick up where the main tab left off
+- The Pop-out button URL carries `&play=1`. `radio.js` reads it from the localized config and auto-calls `audio.play()` 200 ms after init. Same-origin user-gesture popups are exempt from autoplay-blocking on every modern browser, so it just works.
+- On opening the popup, **every other audio surface in the main tab is paused** so you don't end up with two streams running simultaneously.
+
+### Popup details
+- Theme follows the user's saved choice (`radio_state['theme']`) — light by default, dark if explicitly set; the popup body gets the `radio-theme-dark` class so the existing dark-mode CSS rules apply.
+- The popup includes everything you need to listen and switch: now-playing block (with dancing bars + Web Audio visualizer), play/pause, mute, volume, full station dropdown grouped by genre, error slot.
+- Close button (`✕`) in the top-right calls `window.close()`.
+- Pop out button **does not appear inside the popup** itself (would be infinite); the JS detects `popoutUrl === ''` in the localized config and hides any Pop-out button it finds.
+- Popup blocked? The button shows a clear alert: *"Pop-out blocked by the browser. Allow popups for this site, then try again."*
+
+### State stays in sync
+- The popup uses the **same `radio_save_state` AJAX endpoint** as the main player. If you change station or volume in the popup, it persists to user_meta; the next time you load any Radio page in the main tab it picks up the new values.
+- Track history continues to log from whichever surface is playing — the popup polls SomaFM and POSTs to `radio_log_track` exactly like the main player.
+
+**Files changed:** `radio.php` (version, `popoutUrl` added to localized config, new `admin_post_radio_popout` action + `radio_render_popout_page` handler with full standalone HTML), `inc/admin-page.php` + `inc/dashboard-widget.php` (Pop-out button beside Play), `assets/css/radio.css` (Pop-out button styling), `assets/js/radio.js` (`bindPopOut` opens the window + pauses other surfaces, autoplay branch reads `cfg.autoPlay`), `inc/about.php` (history entry).
+
+---
+
 ## [0.5.0] — 2026-05-29 — Track history + favourites
 
 SomaFM plays deep cuts you'll never hear again. v0.5.0 quietly logs every track that scrolls past so you can find it again later — and a star button keeps the ones worth keeping forever.
diff --git a/assets/css/radio.css b/assets/css/radio.css
index 9f54646..92d309c 100644
--- a/assets/css/radio.css
+++ b/assets/css/radio.css
@@ -166,6 +166,16 @@
     font-family: "Helvetica Neue", Arial, sans-serif;
 }
 
+/* v0.6.0: Pop-out button — small secondary button beside Play. Uses WP
+   native .button styles; the ↗ glyph signals "opens in another window." */
+.radio-player__popout {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    font-size: 12px;
+}
+.radio-player__popout span[aria-hidden] { font-size: 13px; line-height: 1; }
+
 .radio-player__volume {
     display: flex;
     align-items: center;
diff --git a/assets/js/radio.js b/assets/js/radio.js
index e3d9de1..6e3044d 100644
--- a/assets/js/radio.js
+++ b/assets/js/radio.js
@@ -412,6 +412,44 @@
         }
 
         bindMute(player, audio, volumeIn, volPctEl);
+        bindPopOut(player);
+
+        // v0.6.0: popout auto-resume — when opened with ?play=1, immediately
+        // pick up where the main tab left off. Same-origin user-gesture popups
+        // are exempt from autoplay blocking on every modern browser.
+        if (cfg.autoPlay) {
+            setTimeout(function () {
+                if (audio.paused) { audio.play().catch(function () { /* autoplay denied — user just clicks play */ }); }
+            }, 200);
+        }
+    }
+
+    /** v0.6.0: Pop-out window button. Opens a 380×560 standalone window
+     *  with just the player chrome (no WP admin), via admin-post.php?
+     *  action=radio_popout&play=1. The popup persists across main-tab
+     *  navigation so background music doesn't cut when you move around
+     *  the WP admin. Pauses every other audio surface in this tab so
+     *  there's only one stream playing at a time. */
+    function bindPopOut(player) {
+        var btn = player.querySelector('[data-radio-popout]');
+        if (!btn) { return; }
+        if (!cfg.popoutUrl) { btn.style.display = 'none'; return; } // already in popout
+        btn.addEventListener('click', function () {
+            var w = window.open(
+                cfg.popoutUrl + '&play=1',
+                'radio_popout',
+                'width=380,height=560,resizable=yes,scrollbars=no,toolbar=no,location=no,menubar=no,status=no'
+            );
+            if (!w) {
+                window.alert('Pop-out blocked by the browser. Allow popups for this site, then try again.');
+                return;
+            }
+            w.focus();
+            // Pause every audio surface in this tab — the popup is the new player.
+            document.querySelectorAll('[data-radio-audio]').forEach(function (a) {
+                if (!a.paused) { a.pause(); }
+            });
+        });
     }
 
     /** Keep all .radio-player surfaces on the same station. */
diff --git a/inc/about.php b/inc/about.php
index a3ca4b4..37f4e6a 100644
--- a/inc/about.php
+++ b/inc/about.php
@@ -48,7 +48,11 @@ function radio_render_about_page() {
                 <h2><?php esc_html_e( 'Version history', 'radio' ); ?></h2>
                 <ul>
                     <li>
-                        <span class="ver">v0.5.0</span> &mdash; 29 May 2026 <span class="latest">latest</span><br>
+                        <span class="ver">v0.6.0</span> &mdash; 30 May 2026 <span class="latest">latest</span><br>
+                        <?php esc_html_e( 'Pop-out mini-player. A small "↗ Pop out" button next to Play opens the player in its own 380×560 window. The popup persists across the main tab\'s navigation, so the music keeps playing while you click around Plugins / Posts / Users. The popup auto-resumes where the main tab left off, pauses the main-tab audio so you don\'t double-stream, and uses the same state + history + favourites as everywhere else.', 'radio' ); ?>
+                    </li>
+                    <li>
+                        <span class="ver">v0.5.0</span> &mdash; 29 May 2026<br>
                         <?php esc_html_e( 'Track history + favourites. Every track that scrolls past in the player is now quietly logged to your personal Radio → History page (capped at 500), with a star toggle to keep the good ones forever in a separate Favourites tab. Each row has four search links (Spotify / YouTube / Apple Music / Bandcamp) so you can find that track on whichever service you use. Filter by station, search by artist or title, clear history with a button. Per-user, nothing leaves your site.', 'radio' ); ?>
                     </li>
                     <li>
diff --git a/inc/admin-page.php b/inc/admin-page.php
index 4909054..8efb0f8 100644
--- a/inc/admin-page.php
+++ b/inc/admin-page.php
@@ -58,6 +58,10 @@ function radio_render_main_page() {
                             <span data-radio-play-label><?php esc_html_e( 'Play', 'radio' ); ?></span>
                         </button>
 
+                        <button type="button" class="button radio-player__popout" data-radio-popout title="<?php esc_attr_e( 'Open in a pop-out window — keeps playing while you navigate the admin', 'radio' ); ?>">
+                            <span aria-hidden="true">↗</span> <?php esc_html_e( 'Pop out', 'radio' ); ?>
+                        </button>
+
                         <div class="radio-player__volume">
                             <button type="button" class="radio-player__mute" data-radio-mute aria-label="<?php esc_attr_e( 'Mute', 'radio' ); ?>">
                                 <span class="dashicons dashicons-controls-volumeon" aria-hidden="true"></span>
diff --git a/inc/dashboard-widget.php b/inc/dashboard-widget.php
index 0965456..530f832 100644
--- a/inc/dashboard-widget.php
+++ b/inc/dashboard-widget.php
@@ -51,6 +51,10 @@ function radio_render_dashboard_widget() {
                 <span data-radio-play-label><?php esc_html_e( 'Play', 'radio' ); ?></span>
             </button>
 
+            <button type="button" class="button radio-player__popout" data-radio-popout title="<?php esc_attr_e( 'Open in a pop-out window — keeps playing while you navigate', 'radio' ); ?>">
+                <span aria-hidden="true">↗</span> <?php esc_html_e( 'Pop out', 'radio' ); ?>
+            </button>
+
             <div class="radio-player__volume">
                 <button type="button" class="radio-player__mute" data-radio-mute aria-label="<?php esc_attr_e( 'Mute', 'radio' ); ?>">
                     <span class="dashicons dashicons-controls-volumeon" aria-hidden="true"></span>
diff --git a/radio.php b/radio.php
index d29bae4..c0837e7 100644
--- a/radio.php
+++ b/radio.php
@@ -5,7 +5,7 @@
  * Plugin Name: Radio
  * Plugin URI:  https://icanhelp.ie/radio
  * Description: A small, focused, free radio player for your WordPress admin. 44 SomaFM stations grouped by 10 genres — ambient, electronic, lounge, rock, metal, jazz, world, reggae, holiday, specials. Plays via HTML5 audio; volume + station choice persist per-user.
- * Version:     0.5.0
+ * Version:     0.6.0
  * Requires at least: 5.0
  * Requires PHP: 7.4
  * Author:      David Keane
@@ -20,7 +20,7 @@
 if ( ! defined( 'ABSPATH' ) ) { exit; }
 
 // Plugin coordinates.
-if ( ! defined( 'RADIO_VERSION' ) )   { define( 'RADIO_VERSION',   '0.5.0' ); }
+if ( ! defined( 'RADIO_VERSION' ) )   { define( 'RADIO_VERSION',   '0.6.0' ); }
 if ( ! defined( 'RADIO_FILE' ) )      { define( 'RADIO_FILE',      __FILE__ ); }
 if ( ! defined( 'RADIO_PATH' ) )      { define( 'RADIO_PATH',      plugin_dir_path( __FILE__ ) ); }
 if ( ! defined( 'RADIO_URL' ) )       { define( 'RADIO_URL',       plugin_dir_url( __FILE__ ) ); }
@@ -131,6 +131,7 @@ function radio_enqueue_admin_assets( $hook ) {
         'stations'  => radio_get_stations_flat(),
         'ajaxUrl'   => admin_url( 'admin-ajax.php' ),
         'nonce'     => wp_create_nonce( 'radio_save_state' ),
+        'popoutUrl' => admin_url( 'admin-post.php?action=radio_popout' ),
         'strings'   => array(
             'play'         => __( 'Play', 'radio' ),
             'pause'        => __( 'Pause', 'radio' ),
@@ -221,6 +222,139 @@ function radio_ajax_clear_history() {
     wp_send_json_success();
 }
 
+/**
+ * v0.6.0 — Pop-out mini player. Renders a standalone HTML page (no WP
+ * admin chrome) at `admin-post.php?action=radio_popout`, opened by the
+ * JS via `window.open()`. The popup persists across main-tab navigation
+ * so background music keeps playing when the user moves around the
+ * admin. `&play=1` in the URL tells `radio.js` to auto-resume on load.
+ */
+add_action( 'admin_post_radio_popout', 'radio_render_popout_page' );
+function radio_render_popout_page() {
+    if ( ! current_user_can( 'read' ) ) {
+        wp_die( esc_html__( 'You do not have permission to view this page.', 'radio' ) );
+    }
+
+    $state    = radio_get_state();
+    $station  = radio_find_station( $state['station_id'] );
+    $stations = radio_get_stations_grouped();
+    $theme    = isset( $state['theme'] ) ? $state['theme'] : 'auto';
+    if ( ! in_array( $theme, array( 'auto', 'light', 'dark' ), true ) ) { $theme = 'auto'; }
+
+    $cfg = array(
+        'state'     => $state,
+        'stations'  => radio_get_stations_flat(),
+        'ajaxUrl'   => admin_url( 'admin-ajax.php' ),
+        'nonce'     => wp_create_nonce( 'radio_save_state' ),
+        'popoutUrl' => '', // already in popout — no further popouts
+        'autoPlay'  => isset( $_GET['play'] ), // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- query flag only, no state change
+        'strings'   => array(
+            'play'         => __( 'Play', 'radio' ),
+            'pause'        => __( 'Pause', 'radio' ),
+            'loading'      => __( 'Loading…', 'radio' ),
+            'error'        => __( 'Stream error — try another station.', 'radio' ),
+            'saveError'    => __( 'Preferences not saved — check your connection.', 'radio' ),
+            'mute'         => __( 'Mute', 'radio' ),
+            'unmute'       => __( 'Unmute', 'radio' ),
+            'nowPlaying'   => __( 'Now Playing', 'radio' ),
+            'volume'       => __( 'Volume', 'radio' ),
+            'station'      => __( 'Station', 'radio' ),
+        ),
+    );
+    ?>
+<!DOCTYPE html>
+<html lang="<?php echo esc_attr( str_replace( '_', '-', get_bloginfo( 'language' ) ) ); ?>">
+<head>
+    <meta charset="<?php bloginfo( 'charset' ); ?>">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title><?php printf( esc_html__( 'Radio — %s', 'radio' ), esc_html( $station['name'] ) ); ?></title>
+    <link rel="stylesheet" href="<?php echo esc_url( includes_url( 'css/dashicons.min.css' ) ); ?>?ver=<?php echo esc_attr( get_bloginfo( 'version' ) ); ?>">
+    <link rel="stylesheet" href="<?php echo esc_url( RADIO_URL . 'assets/css/radio.css' ); ?>?ver=<?php echo esc_attr( RADIO_VERSION ); ?>">
+    <style>
+        :root { --wp-admin-theme-color: #2271b1; }
+        html, body { margin: 0; padding: 0; }
+        body { padding: 14px; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; background: #f0f0f1; color: #1d2327; font-size: 13px; }
+        .radio-popout-header { display: flex; justify-content: space-between; align-items: center; margin: 0 0 12px; }
+        .radio-popout-header h1 { margin: 0; font-size: 14px; font-weight: 600; color: #1d2327; }
+        .radio-popout-header h1::before { content: '📻 '; }
+        .radio-popout-close { background: none; border: 0; font-size: 18px; cursor: pointer; color: #646970; padding: 4px 8px; line-height: 1; border-radius: 3px; }
+        .radio-popout-close:hover { color: #b32d2e; background: rgba(179,45,46,0.08); }
+        .radio-popout-wrap { background: #fff; border: 1px solid #c3c4c7; padding: 14px; border-radius: 3px; }
+        .radio-popout-wrap .radio-player__station-select select { max-width: 100%; }
+        .radio-popout-wrap .radio-player__volume { width: 100%; }
+        .radio-popout-wrap .radio-player__controls { flex-direction: column; align-items: stretch; gap: 10px; }
+        body.radio-theme-dark { background: #101213; color: #f0f0f1; }
+        body.radio-theme-dark .radio-popout-header h1 { color: #f0f0f1; }
+        body.radio-theme-dark .radio-popout-wrap { background: #1d2327; border-color: #3c434a; }
+        body.radio-theme-dark .radio-popout-close { color: #a7aaad; }
+    </style>
+</head>
+<body class="radio-popout radio-theme-<?php echo esc_attr( $theme ); ?>">
+
+    <div class="radio-popout-header">
+        <h1><?php esc_html_e( 'Radio', 'radio' ); ?></h1>
+        <button type="button" class="radio-popout-close" onclick="window.close()" title="<?php esc_attr_e( 'Close', 'radio' ); ?>">✕</button>
+    </div>
+
+    <div class="radio-popout-wrap">
+        <div class="radio-player" data-radio-surface="popout">
+
+            <div class="radio-player__now">
+                <span class="radio-player__indicator" aria-hidden="true">
+                    <span class="radio-player__bars"><span></span><span></span><span></span><span></span></span>
+                    <canvas class="radio-player__viz" data-radio-viz hidden></canvas>
+                </span>
+                <span class="radio-player__label"><?php esc_html_e( 'Now Playing', 'radio' ); ?></span>
+                <span class="radio-player__station-name" data-radio-name><?php echo esc_html( $station['name'] ); ?></span>
+                <span class="radio-player__station-genre" data-radio-genre><?php echo esc_html( $station['genre'] ); ?></span>
+                <p class="radio-player__station-desc" data-radio-desc><?php echo esc_html( $station['description'] ); ?></p>
+                <p class="radio-player__track" data-radio-track hidden></p>
+            </div>
+
+            <div class="radio-player__controls">
+                <button type="button" class="button button-primary radio-player__play" data-radio-play>
+                    <span class="radio-player__play-glyph" data-radio-play-glyph aria-hidden="true">&#9654;</span>
+                    <span data-radio-play-label><?php esc_html_e( 'Play', 'radio' ); ?></span>
+                </button>
+                <div class="radio-player__volume">
+                    <button type="button" class="radio-player__mute" data-radio-mute aria-label="<?php esc_attr_e( 'Mute', 'radio' ); ?>">
+                        <span class="dashicons dashicons-controls-volumeon" aria-hidden="true"></span>
+                    </button>
+                    <input type="range" min="0" max="100" value="<?php echo esc_attr( (int) round( $state['volume'] * 100 ) ); ?>" data-radio-volume aria-label="<?php esc_attr_e( 'Volume', 'radio' ); ?>">
+                    <span class="radio-player__volume-pct" data-radio-volume-pct><?php echo esc_html( (int) round( $state['volume'] * 100 ) ); ?>%</span>
+                </div>
+            </div>
+
+            <div class="radio-player__station-select">
+                <label for="radio-station-popout"><?php esc_html_e( 'Station', 'radio' ); ?></label>
+                <select id="radio-station-popout" data-radio-station>
+                    <?php foreach ( $stations as $genre => $entries ) :
+                        if ( empty( $entries ) ) { continue; }
+                        ?>
+                        <optgroup label="<?php echo esc_attr( $genre ); ?>">
+                            <?php foreach ( $entries as $entry ) : ?>
+                                <option value="<?php echo esc_attr( $entry['id'] ); ?>" data-url="<?php echo esc_attr( $entry['url'] ); ?>" data-desc="<?php echo esc_attr( $entry['description'] ); ?>" data-genre="<?php echo esc_attr( $entry['genre'] ); ?>" <?php selected( $entry['id'], $state['station_id'] ); ?>>
+                                    <?php echo esc_html( $entry['name'] ); ?>
+                                </option>
+                            <?php endforeach; ?>
+                        </optgroup>
+                    <?php endforeach; ?>
+                </select>
+            </div>
+
+            <div class="radio-player__error" data-radio-error hidden></div>
+            <audio data-radio-audio preload="none" crossorigin="anonymous"></audio>
+        </div>
+    </div>
+
+    <script>window.RadioPlugin = <?php echo wp_json_encode( $cfg ); ?>;</script>
+    <script src="<?php echo esc_url( RADIO_URL . 'assets/js/radio.js' ); ?>?ver=<?php echo esc_attr( RADIO_VERSION ); ?>"></script>
+</body>
+</html>
+    <?php
+    exit;
+}
+
 /**
  * Surface the user's theme choice (auto/light/dark) to CSS as a body
  * class. `radio-theme-dark` forces dark; `radio-theme-auto` lets the