feat(v0.4.1-prep): back link from Options page to Tuner main UI

David flagged 2026-06-09 night: 'when i click the settings button i
go to settings but we have no back link to radio'. Real UX gap —
Options was a one-way trip. The popup auto-closes on launch and the
NewTab is in a different tab, so there was no obvious way back.

Fix: the existing brand header (helmet + 'RangerHQ Tuner — Options'
title) is now a single anchor pointing at newtab.html. Adds a small ←
glyph to the left of the helmet that hover-shifts left + colour-shifts
to accent green for a clear back-affordance.

Same-tab navigation (just an href, no chrome.tabs.create) so the user
doesn't accumulate Tuner tabs. They came IN via Options, they go OUT
into the player UI in the same tab.

Aria: the ← is hidden from screen readers (decorative); the title
attribute on the anchor gives the accessible label.

2 files, +24 lines, 4 lines modified in existing .opt-brand block.

Branch: v0.4.1-prep — not for immediate ship since v0.4.0 is still
in Web Store re-review. Bundle this with light-mode + other polish
into v0.5.0 OR ship as quick v0.4.1 patch after v0.4.0 clears.

CHANGELOG.md

@@ -7,11 +7,60 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) — versi
 
 ## [Unreleased]
 
-### Planned — Tier 3 (Chrome Web Store submission)
-- Listing assets: 1280x800 screenshots, 440x280 promo tile
-- Privacy policy URL published at `davidtkeane.com/rangerhq-tuner/privacy`
-- 2-Step Verification on Google account
-- $5 dev fee + submission
+### Planned — Tier 2 polish (next)
+- Light mode support (`prefers-color-scheme` + flipped palette across popup / NewTab / Options)
+- `.m3u` parser alongside `.pls` to widen future-adapter compatibility
+- Station artwork lazy-load + fallback to family helmet
+- Better error UI for failed streams ("Stream unavailable, try another")
+- `.crx` packaging instructions in README for sideload users
+
+---
+
+## [0.4.0] — 2026-06-09 — First-run UX hint
+
+First post-launch update, shipped the same day v0.3.0 went LIVE on the Chrome Web Store. Pure UX polish — zero new permissions, zero new code dependencies, zero behaviour change for existing users.
+
+### Added — Discoverable "pick a station to begin" affordance
+
+Triggered by David's own 30-second panic on first Web Store install (uninstalled the dev build, installed from the Web Store fresh, hit Play, got nothing, then realised "ah, I need to pick a station first"). The product worked correctly — the dev build had a seeded station from hours of testing, the fresh install does not — but the 30-second panic exposed a real first-run-UX gap.
+
+**Two layered cues, both pure CSS driven by a `body.is-first-run` class:**
+
+1. **Subtle accent-green glow pulses** around the station list (popup) and the Quick Stations chip row (NewTab). Uses a 2.4-second `box-shadow` keyframe at low alpha (0.18-0.25) — visible but not noisy.
+2. **Bouncing ↓ arrow** appended to the "Pick a station to begin" text in both surfaces. Uses an `::after` pseudo-element with a 1.8-second `translateY` keyframe.
+
+The `is-first-run` class is toggled by a tiny `reflectFirstRunHint()` function called from:
+- `init()` once stations + `currentStation` are resolved
+- `onPickStation()` the moment a user picks
+- the `chrome.storage.onChanged` listener when another surface picks (so the hint disappears on both surfaces simultaneously via cross-surface sync)
+
+Existing users with a stored `tuner.currentStationId` never see either cue — the class only attaches when `currentStation` is null.
+
+### Files touched
+
+- `src/popup/popup.css` (+35 lines — keyframes + `.is-first-run` rules)
+- `src/popup/popup.js` (+11 lines — `reflectFirstRunHint()` + 3 call sites)
+- `src/newtab/newtab.css` (+36 lines — same idea, NewTab-namespaced)
+- `src/newtab/newtab.js` (+10 lines — same pattern)
+
+Total: 4 files, +92 lines, 0 deletions.
+
+### Not changed
+
+- No new permissions
+- No new host_permissions
+- No new external libraries
+- No change to `manifest.json` beyond the version bump and CHANGELOG-referenced URL
+- No data migration required (no storage shape change)
+
+### Same-day context
+
+This update ships the same day:
+- v0.3.0 went LIVE on the Chrome Web Store (~17:08 Dublin, ~15.5h after submission)
+- RangerHQ Radio v1.0.0 stability milestone went LIVE on WordPress.org (~21:51 Dublin)
+- David received a PhD-prep signal from his Research in Computing lecturer at NCI Dublin
+
+A solid day.
 
 ---
 

manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "RangerHQ Tuner",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Lightweight SomaFM radio player. Logs what plays. One-click search to Spotify, YouTube, Apple Music, Bandcamp. No telemetry.",
   "author": "David Keane",
   "homepage_url": "https://davidtkeane.com/rangerhq-tuner",

src/newtab/newtab.css

@@ -585,3 +585,39 @@ body::before {
   .nt-station { font-size: 22px; }
   .nt-station-list { max-height: 220px; }
 }
+
+/* ──────────────────────────────────────────────────────────────────────
+   First-run UX hint (v0.4.0)
+   Subtle accent-green pulse around the Quick Stations row + a bouncing
+   ↓ arrow on the now-playing area. Both disappear the moment a station
+   is picked. Existing users never see them.
+   ────────────────────────────────────────────────────────────────────── */
+
+@keyframes nt-pulse-glow {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(109, 191, 122, 0); }
+  50%      { box-shadow: 0 0 0 6px rgba(109, 191, 122, 0.18); }
+}
+
+@keyframes nt-bounce {
+  0%, 100% { transform: translateY(0); }
+  50%      { transform: translateY(4px); }
+}
+
+body.is-first-run .nt-quick {
+  animation: nt-pulse-glow 2.4s ease-in-out infinite;
+  border-radius: var(--radius);
+  padding: 14px;
+  margin: 0 -14px;
+}
+
+body.is-first-run .nt-track {
+  color: var(--accent);
+  font-weight: 500;
+}
+
+body.is-first-run .nt-track::after {
+  content: " ↓";
+  display: inline-block;
+  animation: nt-bounce 1.8s ease-in-out infinite;
+  margin-left: 6px;
+}

src/newtab/newtab.js

@@ -108,6 +108,7 @@ async function init() {
 
   const currentId = stored[STORAGE_KEYS.currentId];
   currentStation = stations.find(s => s.id === currentId) || null;
+  reflectFirstRunHint();
   renderNow();
   renderQuick();
   renderList();
@@ -184,6 +185,7 @@ async function init() {
       const newId = changes[STORAGE_KEYS.currentId].newValue;
       currentStation = stations.find(s => s.id === newId) || null;
       els.play.disabled = !currentStation;
+      reflectFirstRunHint();
       renderNow();
       renderQuick();
       renderList();
@@ -317,6 +319,7 @@ function renderList() {
 async function onPickStation(station) {
   currentStation = station;
   els.play.disabled = false;
+  reflectFirstRunHint();
   await chrome.storage.local.set({ [STORAGE_KEYS.currentId]: station.id });
   renderNow();
   renderQuick();
@@ -364,6 +367,13 @@ async function onVolume() {
 
 /* ---------- Helpers ---------- */
 
+// v0.4.0 first-run UX hint — body class drives the pulse + arrow CSS in
+// newtab.css. Active when no station has been picked yet; cleared the
+// moment one is selected (here or via cross-surface storage sync).
+function reflectFirstRunHint() {
+  document.body.classList.toggle('is-first-run', !currentStation);
+}
+
 function reflectPlayButton() {
   els.play.setAttribute('aria-pressed', playing ? 'true' : 'false');
   els.play.textContent = playing ? '❚❚ Pause' : '▶ Play';

src/options/options.css

@@ -40,7 +40,29 @@ html, body {
 .opt-brand {
   display: flex;
   align-items: center;
-  gap: 12px;
+  gap: 10px;
+  text-decoration: none;
+  color: inherit;
+  padding: 4px 8px;
+  margin: -4px -8px;
+  border-radius: var(--radius);
+}
+
+.opt-brand:hover {
+  background: var(--bg-row);
+}
+
+.opt-brand:hover .opt-back {
+  color: var(--accent);
+  transform: translateX(-2px);
+}
+
+.opt-back {
+  font-size: 18px;
+  color: var(--fg-muted);
+  line-height: 1;
+  font-weight: 400;
+  transition: color 120ms ease-out, transform 120ms ease-out;
 }
 
 .opt-helmet {

src/options/options.html

@@ -9,10 +9,11 @@
 <body>
 
   <header class="opt-header">
-    <div class="opt-brand">
+    <a href="../newtab/newtab.html" class="opt-brand" title="Back to RangerHQ Tuner">
+      <span class="opt-back" aria-hidden="true">←</span>
       <img src="../assets/img/ranger.png" alt="" class="opt-helmet">
       <h1>RangerHQ Tuner — Options</h1>
-    </div>
+    </a>
     <span class="opt-version" id="opt-version">v—</span>
   </header>
 

src/popup/popup.css

@@ -310,3 +310,38 @@ html, body {
 .station-list::-webkit-scrollbar-track {
   background: transparent;
 }
+
+/* ──────────────────────────────────────────────────────────────────────
+   First-run UX hint (v0.4.0)
+   When body.is-first-run is set (no station picked), the station list
+   subtly pulses with an accent-green glow and the now-playing area gets
+   a bouncing ↓ arrow pointing the user at the list. Both removed the
+   moment a station is picked, so existing users never see them again.
+   ────────────────────────────────────────────────────────────────────── */
+
+@keyframes tuner-pulse-glow {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(109, 191, 122, 0); }
+  50%      { box-shadow: 0 0 0 4px rgba(109, 191, 122, 0.25); }
+}
+
+@keyframes tuner-bounce {
+  0%, 100% { transform: translateY(0); }
+  50%      { transform: translateY(3px); }
+}
+
+body.is-first-run .stations {
+  animation: tuner-pulse-glow 2.4s ease-in-out infinite;
+  border-radius: 6px;
+}
+
+body.is-first-run .np-track {
+  color: var(--accent);
+  font-weight: 500;
+}
+
+body.is-first-run .np-track::after {
+  content: " ↓";
+  display: inline-block;
+  animation: tuner-bounce 1.8s ease-in-out infinite;
+  margin-left: 4px;
+}

src/popup/popup.js

@@ -69,6 +69,7 @@ async function init() {
   // 3. Restore current station selection.
   const currentId = stored[STORAGE_KEYS.currentId];
   currentStation = stations.find(s => s.id === currentId) || null;
+  reflectFirstRunHint();
   renderNowPlaying();
 
   // 4. Render station list.
@@ -121,6 +122,7 @@ async function init() {
       const newId = changes[STORAGE_KEYS.currentId].newValue;
       currentStation = stations.find(s => s.id === newId) || null;
       els.btnPlay.disabled = !currentStation;
+      reflectFirstRunHint();
       renderNowPlaying();
       renderStations();
     }
@@ -202,6 +204,7 @@ function renderNowPlaying() {
 async function onPickStation(station) {
   currentStation = station;
   els.btnPlay.disabled = false;
+  reflectFirstRunHint();
   await chrome.storage.local.set({ [STORAGE_KEYS.currentId]: station.id });
   renderNowPlaying();
   renderStations();
@@ -256,6 +259,14 @@ function reflectPlayButton() {
   els.btnPlay.textContent = playing ? '❚❚ Pause' : '▶ Play';
 }
 
+// v0.4.0 first-run UX hint — body class drives the pulse + arrow CSS in
+// popup.css. Active when no station has been picked yet; cleared the
+// moment a station is selected (here or in another surface via storage
+// sync).
+function reflectFirstRunHint() {
+  document.body.classList.toggle('is-first-run', !currentStation);
+}
+
 function setState(state) {
   els.statePill.dataset.state = state;
   els.statePill.textContent = state;