feat(0.5.0): track history + favourites with four search providers

Quietly log every track that scrolls past the player to a per-user
history (capped 500). A star button promotes the good ones to a
separate Favourites tab that doesn't age out. Each row has four
search-provider deep links so you can find the track on whichever
service you use.

Storage
  Two new user_meta keys (separate from radio_state so frequent
  inserts don't churn the player-state blob):
    - radio_history    — capped FIFO of last 500 played tracks
    - radio_favourites — uncapped user-starred list

New page: Radio → History
  - History tab: capped FIFO list, newest first.
  - Favourites tab: starred tracks (uncapped).
  - Each row: when (relative + full timestamp on hover) / station /
    artist — title / four search links / favourite-star toggle.
  - Filter by artist/title (live, client-side) + by station (dropdown).
  - Clear history button (favourites preserved).
  - Search providers: Spotify, YouTube, Apple Music, Bandcamp.
    Deep-link URLs only — no API keys, no third-party JS.

Auto-logging during playback
  fetchTrack (existing 30s SomaFM poll loop) now hands new tracks to
  logTrackIfNew → POST to wp_ajax_radio_log_track. Dedup client-side
  (lastLoggedSig) AND server-side (against last entry in user_meta).
  Junk filtered server-side: (unknown) artist, missing artist/title.

New AJAX endpoints
  - radio_log_track          (nonce radio_save_state — player pages)
  - radio_toggle_favourite   (nonce radio_history — history page only)
  - radio_clear_history      (nonce radio_history — history page only)

Files
  - radio.php (version, require new include, submenu page, asset
    enqueue hook adds radio_page_radio-history, three AJAX endpoints,
    three new localized strings)
  - inc/history.php (NEW — storage helpers + admin page renderer)
  - assets/css/radio.css (history table, toolbar, search-link pills,
    favourite star, dark-theme overrides)
  - assets/js/radio.js (logTrackIfNew wired into fetchTrack;
    bindHistoryPage handles filter/favourite/clear)
  - inc/about.php (history entry)
  - CHANGELOG.md (full entry)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -9,6 +9,41 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) — versi
 
 ---
 
+## [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.
+
+### Added — `Radio → History` admin page (per-user)
+- **History tab** — capped FIFO list of the last 500 played tracks. Each row shows when (relative time, full timestamp on hover), station, *artist — title*, four search links, and a favourite-star toggle.
+- **Favourites tab** — uncapped list of starred tracks. Same row layout. Survives even when the history rolls over.
+- **Filter** by artist/title (live, client-side) and by station (dropdown). **Clear history** button on the History tab — favourites preserved.
+- **Four search providers** per row, brand-tinted on hover: **Spotify** (green), **YouTube** (red), **Apple Music** (pink), **Bandcamp** (teal). Deep-link search URLs only — no API keys, no third-party JS.
+- Empty-state messages on both tabs.
+
+### Added — automatic logging during playback
+- `fetchTrack` (the existing 30s SomaFM polling loop) now hands every new track to a new `logTrackIfNew` helper that POSTs it to `wp_ajax_radio_log_track`.
+- **Dedup**: client-side via `lastLoggedSig` so the 30s polling doesn't re-log the same song; server-side against the last entry in user_meta as belt-and-braces.
+- **Junk filtering**: `(unknown)` artists and entries missing artist *or* title are dropped server-side in `radio_sanitize_entry`.
+
+### Added — per-user storage
+- Two new `user_meta` keys, separate from `radio_state` so frequent track inserts don't churn the player-state blob:
+  - `radio_history` — capped at **500 entries** (~50–80 KB max).
+  - `radio_favourites` — uncapped, expected to stay small (user-curated).
+
+### Added — three new AJAX endpoints
+- `wp_ajax_radio_log_track` — append a track (nonce: `radio_save_state`; player-page only).
+- `wp_ajax_radio_toggle_favourite` — toggle a track in favourites (nonce: `radio_history`; History-page only).
+- `wp_ajax_radio_clear_history` — clear the history list (nonce: `radio_history`; History-page only). Favourites untouched.
+
+### Notes
+- Per-user — nothing is shared, nothing leaves the site. Just your own listening history on your own WP account.
+- **No PII concern** — entries are public station/artist/title strings from SomaFM's own JSON.
+- Search-link UI tints toward each provider's brand colour on hover only — keeps the row visually calm in the default state.
+
+**Files changed:** `radio.php` (version, require, submenu, asset enqueue hook, three AJAX endpoints, three new localized strings), **new** `inc/history.php` (storage helpers + page renderer), `assets/css/radio.css` (history-page table, toolbar, search-link pills, favourite star, dark-theme overrides), `assets/js/radio.js` (`logTrackIfNew` wired into `fetchTrack`; `bindHistoryPage` for filter/favourite/clear), `inc/about.php` (history entry).
+
+---
+
 ## [0.4.0] — 2026-05-29 — Now-playing indicator: dancing bars + Web Audio visualizer
 
 A small visual that instantly says *"this is playing right now."* Two layers — a reliable CSS-only indicator that always works, and a progressive Web Audio upgrade that draws actual frequency data when the browser allows.

assets/css/radio.css

@@ -453,3 +453,105 @@
     border-radius: 3px;
     border: 1px solid #3c434a;
 }
+
+/* ──────────────────────────────────────────────────────────────────
+ * History + Favourites page (v0.5.0)
+ * ─────────────────────────────────────────────────────────────── */
+
+.radio-history-wrap { max-width: 1100px; }
+
+.radio-tab-count {
+    color: #646970;
+    font-weight: 400;
+    margin-left: 2px;
+}
+
+.radio-history-toolbar {
+    display: flex;
+    gap: 10px;
+    align-items: center;
+    margin: 12px 0 16px;
+    flex-wrap: wrap;
+}
+
+.radio-history-toolbar input[type="search"] {
+    flex: 1 1 220px;
+    max-width: 360px;
+}
+.radio-history-toolbar select { max-width: 220px; }
+.radio-history-clear { margin-left: auto !important; }
+
+.radio-history-empty {
+    margin-top: 24px;
+    padding: 24px;
+    background: #fff;
+    border: 1px solid #c3c4c7;
+    color: #50575e;
+    font-style: italic;
+    text-align: center;
+}
+
+.radio-history-table { background: #fff; }
+.radio-history-table th,
+.radio-history-table td { padding: 10px 12px; vertical-align: middle; }
+.radio-history-table th.when,
+.radio-history-table th.station,
+.radio-history-table th.fav { white-space: nowrap; }
+.radio-history-table .when,
+.radio-history-table .station {
+    color: #646970; font-size: 12px; white-space: nowrap;
+}
+.radio-history-table .track { font-size: 14px; }
+.radio-history-table .track strong { color: #1d2327; }
+.radio-history-table .search { white-space: nowrap; }
+.radio-history-table .fav { text-align: center; width: 42px; }
+
+/* Search-link pills, brand-tinted on hover */
+.radio-search-link {
+    display: inline-block;
+    padding: 2px 8px;
+    margin-right: 4px;
+    font-size: 11px;
+    font-weight: 600;
+    border-radius: 10px;
+    text-decoration: none;
+    background: #e2e4e7;
+    color: #1d2327;
+    transition: background 0.15s ease, color 0.15s ease;
+}
+.radio-search-link:hover                 { background: #d0d3d6; }
+.radio-search-link--spotify:hover        { background: #1ed760; color: #000; }
+.radio-search-link--youtube:hover        { background: #ff0000; color: #fff; }
+.radio-search-link--apple:hover          { background: #fa57c1; color: #fff; }
+.radio-search-link--bandcamp:hover       { background: #629aa9; color: #fff; }
+
+/* Favourite star — grey by default, golden when starred */
+.radio-fav-btn {
+    background: none;
+    border: 0;
+    padding: 4px 6px;
+    cursor: pointer;
+    font-size: 18px;
+    line-height: 1;
+    color: #c3c4c7;
+    transition: transform 0.12s ease, color 0.12s ease;
+}
+.radio-fav-btn:hover { transform: scale(1.2); color: #f0b849; }
+.radio-fav-btn:focus { outline: 2px solid var(--wp-admin-theme-color, #2271b1); outline-offset: 1px; }
+.radio-fav-btn.is-fav { color: #f0b849; }
+.radio-fav-btn[disabled] { opacity: 0.5; cursor: progress; }
+
+/* Filtered-out rows hidden via JS */
+.radio-history-row.is-filtered { display: none; }
+
+/* Dark theme — history surfaces */
+.radio-theme-dark .radio-history-table { background: #1d2327; color: #c3c4c7; border-color: #3c434a; }
+.radio-theme-dark .radio-history-table th { background: #2c3338; color: #f0f0f1; border-bottom-color: #3c434a; }
+.radio-theme-dark .radio-history-table .track strong { color: #f0f0f1; }
+.radio-theme-dark .radio-history-table .when,
+.radio-theme-dark .radio-history-table .station { color: #a7aaad; }
+.radio-theme-dark .radio-search-link { background: #2c3338; color: #c3c4c7; }
+.radio-theme-dark .radio-history-empty { background: #1d2327; border-color: #3c434a; color: #c3c4c7; }
+.radio-theme-dark .radio-fav-btn { color: #50575e; }
+.radio-theme-dark .radio-fav-btn.is-fav,
+.radio-theme-dark .radio-fav-btn:hover { color: #f0b849; }

assets/js/radio.js

@@ -109,7 +109,8 @@
     }
 
     /** SomaFM current-track polling. Best-effort: stays hidden if the API
-     *  is unreachable / CORS-blocked (the plugin keeps working regardless). */
+     *  is unreachable / CORS-blocked (the plugin keeps working regardless).
+     *  v0.5.0: hands new tracks to logTrackIfNew so they land in user history. */
     function startTrackPolling(player, station) {
         stopTrackPolling(player);
         var trackEl = player.querySelector('[data-radio-track]');
@@ -129,6 +130,7 @@
                     if (!title && !artist) { trackEl.hidden = true; return; }
                     trackEl.textContent = artist ? (title + ' — ' + artist) : title;
                     trackEl.hidden = false;
+                    logTrackIfNew(artist, title, station);
                 })
                 .catch(function () { trackEl.hidden = true; });
         }
@@ -136,6 +138,29 @@
         player._trackTimer = setInterval(fetchTrack, 30000);
     }
 
+    /** v0.5.0: POST a newly-played track to the server history.
+     *  Deduped client-side via lastLoggedSig so consecutive polls of the
+     *  same song don't spam the endpoint (server dedups too as belt+braces). */
+    var lastLoggedSig = '';
+    function logTrackIfNew(artist, title, station) {
+        if (!cfg.ajaxUrl || !cfg.nonce) { return; }
+        if (!artist || !title) { return; }
+        if (artist.toLowerCase() === '(unknown)') { return; }
+        var sig = (artist + '|' + title + '|' + ((station && station.id) || '')).toLowerCase();
+        if (sig === lastLoggedSig) { return; }
+        lastLoggedSig = sig;
+
+        var fd = new FormData();
+        fd.append('action',     'radio_log_track');
+        fd.append('nonce',      cfg.nonce);
+        fd.append('artist',     artist);
+        fd.append('title',      title);
+        fd.append('station',    (station && station.name) || '');
+        fd.append('station_id', (station && station.id)   || '');
+        fetch(cfg.ajaxUrl, { method: 'POST', credentials: 'same-origin', body: fd })
+            .catch(function () { /* track log is best-effort */ });
+    }
+
     function stopTrackPolling(player) {
         if (player._trackTimer) {
             clearInterval(player._trackTimer);
@@ -435,10 +460,79 @@
         });
     }
 
+    /** v0.5.0: wire the History admin page — filter, favourite-toggle,
+     *  clear-history. No-op on pages without these elements. */
+    function bindHistoryPage() {
+        var searchIn   = document.getElementById('radio-history-search');
+        var stationSel = document.getElementById('radio-history-station');
+        var rows       = document.querySelectorAll('.radio-history-row');
+        var clearBtn   = document.getElementById('radio-history-clear');
+
+        function applyFilter() {
+            if (!rows.length) { return; }
+            var q = (searchIn ? searchIn.value : '').toLowerCase().trim();
+            var s = stationSel ? stationSel.value : '';
+            rows.forEach(function (row) {
+                var matchQ = !q || (row.dataset.search || '').indexOf(q) !== -1;
+                var matchS = !s || row.dataset.stationId === s;
+                row.classList.toggle('is-filtered', !(matchQ && matchS));
+            });
+        }
+        if (searchIn)   { searchIn.addEventListener('input',  applyFilter); }
+        if (stationSel) { stationSel.addEventListener('change', applyFilter); }
+
+        // Favourite-toggle buttons (per row)
+        document.querySelectorAll('.radio-fav-btn').forEach(function (btn) {
+            btn.addEventListener('click', function () {
+                var fd = new FormData();
+                fd.append('action',     'radio_toggle_favourite');
+                fd.append('nonce',      btn.dataset.nonce || '');
+                fd.append('artist',     btn.dataset.artist || '');
+                fd.append('title',      btn.dataset.title || '');
+                fd.append('station',    btn.dataset.station || '');
+                fd.append('station_id', btn.dataset.stationId || '');
+                btn.disabled = true;
+                fetch(cfg.ajaxUrl, { method: 'POST', credentials: 'same-origin', body: fd })
+                    .then(function (r) { return r.json(); })
+                    .then(function (res) {
+                        btn.disabled = false;
+                        if (!res || !res.success) { return; }
+                        var isFav = !!(res.data && res.data.favourite);
+                        btn.classList.toggle('is-fav', isFav);
+                        btn.textContent = isFav ? '★' : '☆';
+                        btn.setAttribute('aria-label', isFav
+                            ? (cfg.strings.removeFav || 'Remove from favourites')
+                            : (cfg.strings.addFav    || 'Add to favourites'));
+                    })
+                    .catch(function () { btn.disabled = false; });
+            });
+        });
+
+        // Clear-history button (history tab only)
+        if (clearBtn) {
+            clearBtn.addEventListener('click', function () {
+                var msg = cfg.strings.clearConfirm || 'Clear all track history? (Favourites are kept.)';
+                if (!window.confirm(msg)) { return; }
+                var fd = new FormData();
+                fd.append('action', 'radio_clear_history');
+                fd.append('nonce',  clearBtn.dataset.nonce || '');
+                clearBtn.disabled = true;
+                fetch(cfg.ajaxUrl, { method: 'POST', credentials: 'same-origin', body: fd })
+                    .then(function (r) { return r.json(); })
+                    .then(function (res) {
+                        if (res && res.success) { window.location.reload(); }
+                        else { clearBtn.disabled = false; }
+                    })
+                    .catch(function () { clearBtn.disabled = false; });
+            });
+        }
+    }
+
     function init() {
         var players = document.querySelectorAll('.radio-player');
         for (var i = 0; i < players.length; i++) { bindPlayer(players[i]); }
         bindSettingsSlider();
+        bindHistoryPage();
     }
 
     if (document.readyState === 'loading') {

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.4.0</span> &mdash; 29 May 2026 <span class="latest">latest</span><br>
+                        <span class="ver">v0.5.0</span> &mdash; 29 May 2026 <span class="latest">latest</span><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>
+                        <span class="ver">v0.4.0</span> &mdash; 29 May 2026<br>
                         <?php esc_html_e( 'Now-playing visual indicator. Four tiny dancing bars next to "Now Playing" pulse while the audio is playing (pure CSS, always works). On top of that, a Web Audio frequency visualizer tries to draw live frequency bars on a small canvas — if the browser allows it and the stream is CORS-friendly it kicks in automatically; if not, the CSS bars stay and nothing breaks.', 'radio' ); ?>
                     </li>
                     <li>

inc/history.php

@@ -0,0 +1,255 @@
+<?php
+/**
+ * Radio — track history + favourites (v0.5.0).
+ *
+ * Storage: two per-user `wp_usermeta` keys, separate from `radio_state`
+ * so frequent track logging doesn't rewrite the whole state blob.
+ *   radio_history    — capped FIFO list of recently played tracks
+ *   radio_favourites — uncapped list of user-starred tracks
+ *
+ * Entry shape:
+ *   array(
+ *     'artist'     => string,
+ *     'title'      => string,
+ *     'station'    => string,    // display name e.g. "DEF CON Radio"
+ *     'station_id' => string,    // e.g. "soma-defcon"
+ *     'at'         => int,       // unix timestamp
+ *   )
+ */
+
+if ( ! defined( 'ABSPATH' ) ) { exit; }
+
+const RADIO_HISTORY_KEY    = 'radio_history';
+const RADIO_FAVOURITES_KEY = 'radio_favourites';
+const RADIO_HISTORY_CAP    = 500;
+
+/** Current user's track history (oldest first). */
+function radio_get_history( $user_id = 0 ) {
+    $user_id = $user_id ? (int) $user_id : get_current_user_id();
+    if ( ! $user_id ) { return array(); }
+    $h = get_user_meta( $user_id, RADIO_HISTORY_KEY, true );
+    return is_array( $h ) ? $h : array();
+}
+
+/** Current user's favourited tracks (oldest first). */
+function radio_get_favourites( $user_id = 0 ) {
+    $user_id = $user_id ? (int) $user_id : get_current_user_id();
+    if ( ! $user_id ) { return array(); }
+    $f = get_user_meta( $user_id, RADIO_FAVOURITES_KEY, true );
+    return is_array( $f ) ? $f : array();
+}
+
+/** Normalise raw POSTed track data; returns null on junk input. */
+function radio_sanitize_entry( $entry ) {
+    if ( ! is_array( $entry ) ) { return null; }
+    $artist     = isset( $entry['artist'] )     ? sanitize_text_field( wp_unslash( $entry['artist'] ) )     : '';
+    $title      = isset( $entry['title'] )      ? sanitize_text_field( wp_unslash( $entry['title'] ) )      : '';
+    $station    = isset( $entry['station'] )    ? sanitize_text_field( wp_unslash( $entry['station'] ) )    : '';
+    $station_id = isset( $entry['station_id'] ) ? sanitize_key( wp_unslash( $entry['station_id'] ) )        : '';
+    if ( ! $artist || ! $title )                   { return null; }
+    if ( strtolower( $artist ) === '(unknown)' )   { return null; } // SomaFM promo / dead-air placeholder
+    return array(
+        'artist'     => mb_substr( $artist, 0, 200 ),
+        'title'      => mb_substr( $title, 0, 200 ),
+        'station'    => mb_substr( $station, 0, 100 ),
+        'station_id' => $station_id,
+        'at'         => time(),
+    );
+}
+
+/** Dedup signature — artist|title|station_id, lowercased + trimmed. */
+function radio_entry_signature( $entry ) {
+    $a = isset( $entry['artist'] )     ? $entry['artist']     : '';
+    $t = isset( $entry['title'] )      ? $entry['title']      : '';
+    $s = isset( $entry['station_id'] ) ? $entry['station_id'] : '';
+    return strtolower( trim( $a . '|' . $t . '|' . $s ) );
+}
+
+/** Append a track to the user's history, deduped against the last entry
+ *  and capped at RADIO_HISTORY_CAP. Returns true if appended. */
+function radio_log_track( $entry, $user_id = 0 ) {
+    $user_id = $user_id ? (int) $user_id : get_current_user_id();
+    if ( ! $user_id ) { return false; }
+    $clean = radio_sanitize_entry( $entry );
+    if ( ! $clean ) { return false; }
+
+    $history = radio_get_history( $user_id );
+    if ( ! empty( $history ) ) {
+        $last_sig = radio_entry_signature( $history[ count( $history ) - 1 ] );
+        if ( radio_entry_signature( $clean ) === $last_sig ) { return false; }
+    }
+
+    $history[] = $clean;
+    if ( count( $history ) > RADIO_HISTORY_CAP ) {
+        $history = array_slice( $history, -RADIO_HISTORY_CAP );
+    }
+    update_user_meta( $user_id, RADIO_HISTORY_KEY, $history );
+    return true;
+}
+
+/** Toggle whether an entry is favourited. Returns the new state
+ *  (true = now favourited, false = now unfavourited). */
+function radio_toggle_favourite( $entry, $user_id = 0 ) {
+    $user_id = $user_id ? (int) $user_id : get_current_user_id();
+    if ( ! $user_id ) { return false; }
+    $clean = radio_sanitize_entry( $entry );
+    if ( ! $clean ) { return false; }
+    $sig = radio_entry_signature( $clean );
+
+    $favs  = radio_get_favourites( $user_id );
+    $found = -1;
+    foreach ( $favs as $i => $f ) {
+        if ( radio_entry_signature( $f ) === $sig ) { $found = $i; break; }
+    }
+    if ( $found >= 0 ) {
+        array_splice( $favs, $found, 1 );
+        update_user_meta( $user_id, RADIO_FAVOURITES_KEY, $favs );
+        return false;
+    }
+    $favs[] = $clean;
+    update_user_meta( $user_id, RADIO_FAVOURITES_KEY, $favs );
+    return true;
+}
+
+/** Clear the user's history (favourites preserved). */
+function radio_clear_history_all( $user_id = 0 ) {
+    $user_id = $user_id ? (int) $user_id : get_current_user_id();
+    if ( ! $user_id ) { return false; }
+    delete_user_meta( $user_id, RADIO_HISTORY_KEY );
+    return true;
+}
+
+/** URL-build helpers for the four search providers. */
+function radio_search_urls( $artist, $title ) {
+    $enc = rawurlencode( trim( $artist . ' ' . $title ) );
+    return array(
+        'spotify'  => 'https://open.spotify.com/search/' . $enc,
+        'youtube'  => 'https://www.youtube.com/results?search_query=' . $enc,
+        'apple'    => 'https://music.apple.com/search?term=' . $enc,
+        'bandcamp' => 'https://bandcamp.com/search?q=' . $enc,
+    );
+}
+
+/** Render the History admin page (tabs: History / Favourites). */
+function radio_render_history_page() {
+    if ( ! current_user_can( 'read' ) ) {
+        wp_die( esc_html__( 'You do not have permission to view this page.', 'radio' ) );
+    }
+
+    $tab = isset( $_GET['tab'] ) ? sanitize_key( wp_unslash( $_GET['tab'] ) ) : 'history'; // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- tab-switch only, no state change
+    if ( ! in_array( $tab, array( 'history', 'favourites' ), true ) ) { $tab = 'history'; }
+
+    $all_history    = radio_get_history();
+    $all_favourites = radio_get_favourites();
+    $entries        = ( $tab === 'favourites' ) ? $all_favourites : $all_history;
+    $entries        = array_reverse( $entries ); // newest first
+
+    // Set of favourite signatures for fast lookup in the row render.
+    $fav_sigs = array();
+    foreach ( $all_favourites as $f ) { $fav_sigs[ radio_entry_signature( $f ) ] = true; }
+
+    // Stations present in the current tab → filter dropdown options.
+    $stations_in_list = array();
+    foreach ( $entries as $e ) {
+        if ( ! empty( $e['station_id'] ) && ! isset( $stations_in_list[ $e['station_id'] ] ) ) {
+            $stations_in_list[ $e['station_id'] ] = $e['station'];
+        }
+    }
+    asort( $stations_in_list );
+
+    $base_url = admin_url( 'admin.php?page=radio-history' );
+    $hist_url = $base_url . '&tab=history';
+    $fav_url  = $base_url . '&tab=favourites';
+    $nonce    = wp_create_nonce( 'radio_history' );
+    ?>
+    <div class="wrap radio-history-wrap">
+        <h1><?php esc_html_e( 'Radio — Track history', 'radio' ); ?></h1>
+
+        <h2 class="nav-tab-wrapper">
+            <a href="<?php echo esc_url( $hist_url ); ?>" class="nav-tab <?php echo $tab === 'history' ? 'nav-tab-active' : ''; ?>">
+                <?php esc_html_e( 'History', 'radio' ); ?>
+                <span class="radio-tab-count">(<?php echo (int) count( $all_history ); ?>)</span>
+            </a>
+            <a href="<?php echo esc_url( $fav_url ); ?>" class="nav-tab <?php echo $tab === 'favourites' ? 'nav-tab-active' : ''; ?>">
+                ★ <?php esc_html_e( 'Favourites', 'radio' ); ?>
+                <span class="radio-tab-count">(<?php echo (int) count( $all_favourites ); ?>)</span>
+            </a>
+        </h2>
+
+        <?php if ( empty( $entries ) ) : ?>
+            <p class="radio-history-empty">
+                <?php if ( $tab === 'favourites' ) : ?>
+                    <?php esc_html_e( 'No favourites yet — star a track on the History tab to save it here.', 'radio' ); ?>
+                <?php else : ?>
+                    <?php esc_html_e( 'No tracks logged yet. Play some music in the Radio player — tracks will appear here as they play.', 'radio' ); ?>
+                <?php endif; ?>
+            </p>
+        <?php else : ?>
+
+            <div class="radio-history-toolbar">
+                <input type="search" id="radio-history-search" placeholder="<?php esc_attr_e( 'Filter by artist or title…', 'radio' ); ?>" />
+                <select id="radio-history-station">
+                    <option value=""><?php esc_html_e( 'All stations', 'radio' ); ?></option>
+                    <?php foreach ( $stations_in_list as $sid => $sname ) : ?>
+                        <option value="<?php echo esc_attr( $sid ); ?>"><?php echo esc_html( $sname ); ?></option>
+                    <?php endforeach; ?>
+                </select>
+                <?php if ( $tab === 'history' ) : ?>
+                    <button type="button" id="radio-history-clear" class="button radio-history-clear" data-nonce="<?php echo esc_attr( $nonce ); ?>">
+                        🗑 <?php esc_html_e( 'Clear history', 'radio' ); ?>
+                    </button>
+                <?php endif; ?>
+            </div>
+
+            <table class="widefat radio-history-table">
+                <thead>
+                    <tr>
+                        <th class="when"><?php esc_html_e( 'When', 'radio' ); ?></th>
+                        <th class="station"><?php esc_html_e( 'Station', 'radio' ); ?></th>
+                        <th class="track"><?php esc_html_e( 'Artist — Title', 'radio' ); ?></th>
+                        <th class="search"><?php esc_html_e( 'Search', 'radio' ); ?></th>
+                        <th class="fav"><span class="screen-reader-text"><?php esc_html_e( 'Favourite', 'radio' ); ?></span>★</th>
+                    </tr>
+                </thead>
+                <tbody>
+                <?php foreach ( $entries as $e ) :
+                    $sig    = radio_entry_signature( $e );
+                    $is_fav = isset( $fav_sigs[ $sig ] );
+                    $search = radio_search_urls( $e['artist'], $e['title'] );
+                    $ago    = human_time_diff( (int) $e['at'], time() );
+                    ?>
+                    <tr class="radio-history-row" data-station-id="<?php echo esc_attr( $e['station_id'] ); ?>" data-search="<?php echo esc_attr( strtolower( $e['artist'] . ' ' . $e['title'] ) ); ?>">
+                        <td class="when" title="<?php echo esc_attr( wp_date( 'j M Y, H:i', (int) $e['at'] ) ); ?>">
+                            <?php printf( esc_html__( '%s ago', 'radio' ), esc_html( $ago ) ); ?>
+                        </td>
+                        <td class="station"><?php echo esc_html( $e['station'] ); ?></td>
+                        <td class="track">
+                            <strong><?php echo esc_html( $e['artist'] ); ?></strong> &mdash; <?php echo esc_html( $e['title'] ); ?>
+                        </td>
+                        <td class="search">
+                            <a href="<?php echo esc_url( $search['spotify'] );  ?>" target="_blank" rel="noopener" class="radio-search-link radio-search-link--spotify">Spotify</a>
+                            <a href="<?php echo esc_url( $search['youtube'] );  ?>" target="_blank" rel="noopener" class="radio-search-link radio-search-link--youtube">YouTube</a>
+                            <a href="<?php echo esc_url( $search['apple'] );    ?>" target="_blank" rel="noopener" class="radio-search-link radio-search-link--apple">Apple</a>
+                            <a href="<?php echo esc_url( $search['bandcamp'] ); ?>" target="_blank" rel="noopener" class="radio-search-link radio-search-link--bandcamp">Bandcamp</a>
+                        </td>
+                        <td class="fav">
+                            <button type="button"
+                                    class="radio-fav-btn <?php echo $is_fav ? 'is-fav' : ''; ?>"
+                                    data-artist="<?php echo esc_attr( $e['artist'] ); ?>"
+                                    data-title="<?php echo esc_attr( $e['title'] ); ?>"
+                                    data-station="<?php echo esc_attr( $e['station'] ); ?>"
+                                    data-station-id="<?php echo esc_attr( $e['station_id'] ); ?>"
+                                    data-nonce="<?php echo esc_attr( $nonce ); ?>"
+                                    aria-label="<?php echo $is_fav ? esc_attr__( 'Remove from favourites', 'radio' ) : esc_attr__( 'Add to favourites', 'radio' ); ?>">
+                                <?php echo $is_fav ? '★' : '☆'; ?>
+                            </button>
+                        </td>
+                    </tr>
+                <?php endforeach; ?>
+                </tbody>
+            </table>
+
+        <?php endif; ?>
+    </div>
+    <?php
+}

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.4.0
+ * Version:     0.5.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.4.0' ); }
+if ( ! defined( 'RADIO_VERSION' ) )   { define( 'RADIO_VERSION',   '0.5.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__ ) ); }
@@ -34,6 +34,7 @@ require_once RADIO_PATH . 'inc/dashboard-widget.php'; // the compact mini-player
 require_once RADIO_PATH . 'inc/admin-page.php';       // dedicated Radio admin page (larger player)
 require_once RADIO_PATH . 'inc/about.php';            // About page
 require_once RADIO_PATH . 'inc/settings.php';         // Settings page
+require_once RADIO_PATH . 'inc/history.php';          // Track history + favourites (v0.5.0)
 require_once RADIO_PATH . 'inc/updater.php';          // self-hosted update checker against Gitea
 
 /**
@@ -75,6 +76,15 @@ function radio_register_admin_menu() {
         'radio_render_settings_page'
     );
 
+    add_submenu_page(
+        'radio',
+        __( 'Track history', 'radio' ),
+        __( 'History', 'radio' ),
+        'read',
+        'radio-history',
+        'radio_render_history_page'
+    );
+
     add_submenu_page(
         'radio',
         __( 'About', 'radio' ),
@@ -92,10 +102,11 @@ function radio_register_admin_menu() {
 add_action( 'admin_enqueue_scripts', 'radio_enqueue_admin_assets' );
 function radio_enqueue_admin_assets( $hook ) {
     $radio_hooks = array(
-        'index.php',                 // WP Dashboard (the widget lives here)
-        'toplevel_page_radio',       // Radio main page
-        'radio_page_radio-settings', // Settings
-        'radio_page_radio-about',    // About
+        'index.php',                  // WP Dashboard (the widget lives here)
+        'toplevel_page_radio',        // Radio main page
+        'radio_page_radio-settings',  // Settings
+        'radio_page_radio-about',     // About
+        'radio_page_radio-history',   // History + Favourites (v0.5.0)
     );
     if ( ! in_array( $hook, $radio_hooks, true ) ) { return; }
 
@@ -121,16 +132,19 @@ function radio_enqueue_admin_assets( $hook ) {
         'ajaxUrl'   => admin_url( 'admin-ajax.php' ),
         'nonce'     => wp_create_nonce( 'radio_save_state' ),
         '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' ),
+            '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' ),
+            'addFav'       => __( 'Add to favourites', 'radio' ),
+            'removeFav'    => __( 'Remove from favourites', 'radio' ),
+            'clearConfirm' => __( 'Clear all track history? (Favourites are kept.)', 'radio' ),
         ),
     ) );
 }
@@ -162,6 +176,51 @@ function radio_ajax_save_state() {
     wp_send_json_success( radio_get_state() );
 }
 
+/**
+ * AJAX: log a played track to the user's history (v0.5.0).
+ * Nonce: same `radio_save_state` token used for state saves — both come
+ * from the same `wp_localize_script` config available on player pages.
+ */
+add_action( 'wp_ajax_radio_log_track', 'radio_ajax_log_track' );
+function radio_ajax_log_track() {
+    if ( ! is_user_logged_in() ) { wp_send_json_error( 'Not logged in.', 401 ); }
+    check_ajax_referer( 'radio_save_state', 'nonce' );
+    $logged = radio_log_track( array(
+        'artist'     => $_POST['artist']     ?? '',
+        'title'      => $_POST['title']      ?? '',
+        'station'    => $_POST['station']    ?? '',
+        'station_id' => $_POST['station_id'] ?? '',
+    ) );
+    wp_send_json_success( array( 'logged' => (bool) $logged ) );
+}
+
+/**
+ * AJAX: toggle whether a track is favourited.
+ * Nonce: `radio_history` — created fresh per History-page render so the
+ * AJAX is gated to users who actually loaded the page.
+ */
+add_action( 'wp_ajax_radio_toggle_favourite', 'radio_ajax_toggle_favourite' );
+function radio_ajax_toggle_favourite() {
+    if ( ! is_user_logged_in() ) { wp_send_json_error( 'Not logged in.', 401 ); }
+    check_ajax_referer( 'radio_history', 'nonce' );
+    $new_state = radio_toggle_favourite( array(
+        'artist'     => $_POST['artist']     ?? '',
+        'title'      => $_POST['title']      ?? '',
+        'station'    => $_POST['station']    ?? '',
+        'station_id' => $_POST['station_id'] ?? '',
+    ) );
+    wp_send_json_success( array( 'favourite' => (bool) $new_state ) );
+}
+
+/** AJAX: clear the current user's history (favourites preserved). */
+add_action( 'wp_ajax_radio_clear_history', 'radio_ajax_clear_history' );
+function radio_ajax_clear_history() {
+    if ( ! is_user_logged_in() ) { wp_send_json_error( 'Not logged in.', 401 ); }
+    check_ajax_referer( 'radio_history', 'nonce' );
+    radio_clear_history_all();
+    wp_send_json_success();
+}
+
 /**
  * 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