@joewinke/jatui 0.62.0 → 0.63.0

package/dist/ambience/scapes/radio.js

@@ -0,0 +1,297 @@
+import { safeAmbienceHref } from '../groups';
+/** Ramp + teardown timing for the radio scape. */
+export const RADIO = Object.freeze({
+    /** Stepped element-volume fade on stop() — steps per second of fade. */
+    FADE_STEPS_PER_S: 8,
+    /** Pause + de-src this many ms after a stop fade ends — before the
+     *  engine's lookahead retirement (fade*1000 + 250) can drop anything. */
+    TEARDOWN_DELAY_MS: 50
+});
+export function createRadioStreamScape(options) {
+    if (!options?.id)
+        throw new Error('createRadioStreamScape: id is required');
+    if (!options.label)
+        throw new Error('createRadioStreamScape: label is required');
+    if (!options.streamUrl || typeof options.streamUrl !== 'string')
+        throw new Error('createRadioStreamScape: streamUrl is required');
+    // Refuse at create time: a `javascript:`/`data:`/relative stream url
+    // would end up in an <audio> src — http(s) absolute only, the same gate
+    // as every other ambience href.
+    const validated = safeAmbienceHref(options.streamUrl);
+    if (!validated)
+        throw new Error('createRadioStreamScape: streamUrl must be an absolute http(s) url');
+    // Explicitly typed alias: buildInstance is a hoisted declaration, and TS
+    // resets truthiness narrowing at its capture — the guard above is the
+    // build-time refusal this module promises.
+    const streamUrl = validated;
+    const href = safeAmbienceHref(options.href);
+    let mixGain0 = Math.min(1, Math.max(0, options.gain ?? 1));
+    const makeElement = options.createMediaElement ?? ((url) => new Audio(url));
+    /** Shared UI snapshot + subscribers. Only the latest build writes it. */
+    let snap = {
+        status: 'idle',
+        station: options.label,
+        href: href ?? null
+    };
+    const subs = new Set();
+    let instanceSeq = 0;
+    function setSnap(patch) {
+        snap = { ...snap, ...patch };
+        for (const fn of subs)
+            fn(snap);
+    }
+    function buildInstance(scapeCtx) {
+        const instId = ++instanceSeq;
+        let released = false;
+        let started = false;
+        let fading = false;
+        const timers = new Set();
+        let unsub = null;
+        // A plain <audio> element — no crossOrigin (a station stream without
+        // CORS headers must still load), no source node (the tainted-graph
+        // rule would silence it). Loudness is el.volume, below.
+        const el = makeElement(streamUrl);
+        try {
+            // The src is set here, not only via the constructor: an injectable
+            // factory may build a bare element (the real `new Audio(url)` already
+            // carries it), and the tests read the assignment back.
+            el.src = streamUrl;
+            el.preload = 'auto';
+        }
+        catch {
+            /* exotic environments */
+        }
+        const isLive = () => instId === instanceSeq && !released;
+        function atTimer(ms, fn) {
+            if (released)
+                return;
+            const t = setTimeout(() => {
+                timers.delete(t);
+                if (!released)
+                    fn();
+            }, Math.max(0, ms));
+            timers.add(t);
+        }
+        /** The element's loudness right now: the scape gain × the engine's
+         *  master volume (a hand-made test context may omit the hook — it
+         *  then reads full volume). */
+        function elementVolume() {
+            const master = scapeCtx.volume ? scapeCtx.volume() : 1;
+            return Math.min(1, Math.max(0, master)) * Math.min(1, Math.max(0, mixGain0));
+        }
+        function applyVolume() {
+            try {
+                el.volume = Math.min(1, Math.max(0, elementVolume()));
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
+        // The element's own events, so a stream that stalls or dies is
+        // visible in the state surface instead of playing silence.
+        el.addEventListener('playing', () => {
+            if (!isLive() || fading)
+                return;
+            setSnap({ status: 'playing', error: undefined });
+        });
+        el.addEventListener('ended', () => {
+            // A live stream should not end; when it does, say so rather than
+            // showing a playing row over silence.
+            if (!isLive() || fading)
+                return;
+            fail('The stream ended');
+        });
+        el.addEventListener('error', () => {
+            if (!isLive() || fading)
+                return;
+            fail('The stream could not be loaded');
+        });
+        // Mirror the engine's volume on every lookahead tick (~250 ms) so the
+        // volume slider and cross-tab mute reach an element outside the graph.
+        unsub = scapeCtx.lookahead(() => {
+            if (released || !started || fading)
+                return;
+            applyVolume();
+        });
+        function start(_at) {
+            // A superseded (stale) build is inert: only the newest instance may
+            // sound or report — the shared snapshot belongs to the live one.
+            if (started || released || !isLive())
+                return;
+            started = true;
+            setSnap({ status: 'loading', error: undefined });
+            applyVolume();
+            try {
+                const p = el.play();
+                if (p)
+                    p.then(() => {
+                        if (!isLive() || fading)
+                            return;
+                        setSnap({ status: 'playing', error: undefined });
+                    }, () => fail('The stream could not be started'));
+            }
+            catch {
+                fail('The stream could not be started');
+            }
+        }
+        function fail(message) {
+            if (released || !isLive())
+                return;
+            setSnap({ status: 'error', error: message });
+            release();
+        }
+        function release() {
+            if (released)
+                return;
+            released = true;
+            unsub?.();
+            unsub = null;
+            for (const t of timers)
+                clearTimeout(t);
+            timers.clear();
+            try {
+                el.pause();
+            }
+            catch {
+                /* element already unusable */
+            }
+            try {
+                el.removeAttribute('src');
+                el.load();
+            }
+            catch {
+                /* older engines */
+            }
+        }
+        function stop(_at, fade) {
+            if (released)
+                return;
+            setSnap({ status: 'idle', error: undefined });
+            const f = Math.max(0, fade);
+            if (f <= 0) {
+                release();
+                return;
+            }
+            // Stepped element-volume fade (there is no audio-clock gain here):
+            // FADE_STEPS_PER_S steps per fade second, then the wall-clock release.
+            fading = true;
+            const steps = Math.max(1, Math.round(f * RADIO.FADE_STEPS_PER_S));
+            const stepMs = (f * 1000) / steps;
+            for (let i = 1; i <= steps; i++) {
+                atTimer(stepMs * i, () => {
+                    const k = 1 - i / steps;
+                    try {
+                        el.volume = Math.min(1, Math.max(0, elementVolume())) * k;
+                    }
+                    catch {
+                        /* element already unusable */
+                    }
+                });
+            }
+            atTimer(f * 1000 + RADIO.TEARDOWN_DELAY_MS, release);
+        }
+        function setParam(key, value) {
+            if (key !== 'gain' || released)
+                return;
+            mixGain0 = Math.min(1, Math.max(0, value));
+            if (started && !fading)
+                applyVolume();
+        }
+        function pauseInternal() {
+            if (released || !started)
+                return;
+            try {
+                el.pause();
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
+        function resumeInternal() {
+            if (released || !started)
+                return;
+            try {
+                const p = el.play();
+                if (p)
+                    p.catch(() => { }); // the error surface owns failures
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
+        return { start, stop, setParam, pause: pauseInternal, resume: resumeInternal };
+    }
+    const scape = {
+        id: options.id,
+        label: options.label,
+        group: options.group ?? 'radio',
+        description: options.description,
+        radio: true,
+        href: href ?? null,
+        build(scapeCtx) {
+            return buildInstance(scapeCtx);
+        },
+        state: () => snap,
+        subscribe(fn) {
+            subs.add(fn);
+            fn(snap);
+            return () => {
+                subs.delete(fn);
+            };
+        }
+    };
+    return scape;
+}
+/** Narrow a registered scape to a radio stream (to reach its state surface). */
+export function isRadioScape(scape) {
+    return (typeof scape === 'object' &&
+        scape !== null &&
+        scape.radio === true &&
+        typeof scape.subscribe === 'function');
+}
+/**
+ * Build a radio-station item: WITHOUT `streamUrl` an outbound link (the
+ * station's site opens in a new tab — the original, always-available
+ * behavior); WITH `streamUrl` the station's public stream plays right in
+ * the player (client-side fetch from the station — never relayed) and the
+ * site link survives as the attribution target in the now-playing row.
+ *
+ * A `streamUrl` that fails `safeAmbienceHref` (anything but an absolute
+ * http(s) url) is REFUSED: the station falls back to the outbound link and
+ * the bad url is never stored or loaded.
+ */
+export function radioStation(options) {
+    if (options.streamUrl === undefined || options.streamUrl === null) {
+        return {
+            kind: 'link',
+            id: options.id,
+            label: options.label,
+            group: options.group ?? 'radio',
+            href: options.href,
+            description: options.description
+        };
+    }
+    if (!safeAmbienceHref(options.streamUrl)) {
+        // Refused: a typo'd scheme silently dropping the stream would be very
+        // hard to spot from the outside — say so once, then degrade to the
+        // always-available link behavior.
+        if (typeof console !== 'undefined' && typeof console.warn === 'function')
+            console.warn(`radioStation(${options.id}): streamUrl must be an absolute http(s) url — falling back to the outbound link`);
+        return {
+            kind: 'link',
+            id: options.id,
+            label: options.label,
+            group: options.group ?? 'radio',
+            href: options.href,
+            description: options.description
+        };
+    }
+    return createRadioStreamScape({
+        id: options.id,
+        label: options.label,
+        description: options.description,
+        group: options.group,
+        href: options.href,
+        streamUrl: options.streamUrl
+    });
+}

package/dist/ambience/shared.d.ts

@@ -121,6 +121,10 @@ export interface SharedAmbienceState {
      *  null when nothing is playing or the licence forbids redistribution
      *  (jatui-0vxcu). A remote tab's download button reads this. */
     trackDownload: SharedTrackDownload | null;
+    /** The playing playlist's shuffle state (jatui-plbzq), published so a
+     *  remote tab's Shuffle toggle shows the leader's truth. Null when
+     *  unknown (nothing playing, or the scape is not a playlist). */
+    trackShuffle: boolean | null;
 }
 /** An Ambience whose playback is shared across tabs (see module doc). */
 export interface SharedAmbience extends Ambience {
@@ -136,12 +140,16 @@ export interface SharedAmbience extends Ambience {
      *  `position`/`duration`/`title` (jatui-153tz) feed the remote tabs'
      *  now-playing row; nulls mean unknown. `download` (jatui-0vxcu) carries
      *  the track's download info when its licence permits redistribution —
-     *  null clears it. */
-    setNowPlaying(line: string | null, trackIndex?: number | null, position?: number | null, duration?: number | null, title?: string | null, download?: SharedTrackDownload | null): void;
+     *  null clears it. `shuffle` (jatui-plbzq) publishes the playing
+     *  playlist's shuffle state for the remotes' Shuffle toggle. */
+    setNowPlaying(line: string | null, trackIndex?: number | null, position?: number | null, duration?: number | null, title?: string | null, download?: SharedTrackDownload | null, shuffle?: boolean | null): void;
     /** Now-playing-row transport (jatui-153tz): skip / go back one track on a
      *  playlist scape. A remote routes the command to the leader's instance. */
     skipTrack(id: string): void;
     prevTrack(id: string): void;
+    /** Shuffle transport (jatui-plbzq): set the playing playlist's shuffle
+     *  state. A remote routes the command to the leader's instance. */
+    shuffleTrack(id: string, on: boolean): void;
     /** Release the lock, stop the heartbeat and close the channel. The local
      *  engine is killed if this tab was the leader. */
     destroy(): void;

package/dist/ambience/shared.js

@@ -144,6 +144,8 @@ export function createSharedAmbience(options = {}) {
     let nowPlayingDuration = null;
     /** The published track's download info (jatui-0vxcu). */
     let nowPlayingDownload = null;
+    /** The published playlist's shuffle state (jatui-plbzq). */
+    let nowPlayingShuffle = null;
     const ambienceSubs = new Set();
     const sharedSubs = new Set();
     function sharedState() {
@@ -162,7 +164,8 @@ export function createSharedAmbience(options = {}) {
             trackTitle: role === 'leader' ? nowPlayingTitle : (remoteS?.trackTitle ?? null),
             trackPosition: role === 'leader' ? nowPlayingPosition : (remoteS?.trackPosition ?? null),
             trackDuration: role === 'leader' ? nowPlayingDuration : (remoteS?.trackDuration ?? null),
-            trackDownload: role === 'leader' ? nowPlayingDownload : (remoteS?.trackDownload ?? null)
+            trackDownload: role === 'leader' ? nowPlayingDownload : (remoteS?.trackDownload ?? null),
+            trackShuffle: role === 'leader' ? nowPlayingShuffle : (remoteS?.trackShuffle ?? null)
         };
     }
     function ambienceState() {
@@ -232,6 +235,7 @@ export function createSharedAmbience(options = {}) {
         nowPlayingPosition = null;
         nowPlayingDuration = null;
         nowPlayingDownload = null;
+        nowPlayingShuffle = null;
         remoteS = null;
         if (heartbeatTimer) {
             clearInterval(heartbeatTimer);
@@ -471,6 +475,14 @@ export function createSharedAmbience(options = {}) {
                             p?.prev();
                         break;
                     }
+                    case 'shuffle': {
+                        // The Shuffle toggle (jatui-plbzq): routed to the leader's own
+                        // playlist scape instance (its preference persists there).
+                        if (!msg.id)
+                            return;
+                        playlistFor(msg.id)?.setShuffle((msg.arg ?? 0) === 1);
+                        break;
+                    }
                     case 'setVolume':
                         applyVolume(msg.arg ?? userVolume);
                         break;
@@ -644,6 +656,16 @@ export function createSharedAmbience(options = {}) {
         }
         post({ t: 'cmd', cmd: 'prev', id, from: tabId });
     }
+    /** Shuffle transport (jatui-plbzq): set the playing playlist's shuffle
+     *  state — routed to the leader's live instance when this tab is a
+     *  remote (its preference persists there). */
+    function shuffleTrack(id, on) {
+        if (role === 'leader') {
+            playlistFor(id)?.setShuffle(on);
+            return;
+        }
+        post({ t: 'cmd', cmd: 'shuffle', id, arg: on ? 1 : 0, from: tabId });
+    }
     function setVolume(v) {
         applyVolume(v);
         savePersisted(storageKey, {
@@ -713,6 +735,7 @@ export function createSharedAmbience(options = {}) {
         resume,
         skipTrack,
         prevTrack,
+        shuffleTrack,
         kill: () => {
             // A remote has nothing local to kill — tell the leader instead.
             if (role === 'leader')
@@ -723,13 +746,14 @@ export function createSharedAmbience(options = {}) {
         setVolume,
         setMuted,
         toggleMute,
-        setNowPlaying(line, index, position, duration, title, download) {
+        setNowPlaying(line, index, position, duration, title, download, shuffle) {
             nowPlaying = line;
             nowPlayingIndex = line ? (index ?? null) : null;
             nowPlayingPosition = line ? (position ?? null) : null;
             nowPlayingDuration = line ? (duration ?? null) : null;
             nowPlayingTitle = line ? (title ?? null) : null;
             nowPlayingDownload = line ? (download ?? null) : null;
+            nowPlayingShuffle = line ? (shuffle ?? null) : null;
             if (role === 'leader') {
                 publish();
                 emitShared();

package/dist/ambience/types.d.ts

@@ -19,6 +19,13 @@ export interface ScapeContext {
     lookahead: (cb: (now: number) => void) => () => void;
     /** Deterministic-ish random source scoped to the scape instance. */
     rand: () => number;
+    /** The engine's CURRENT master volume, 0..1 (jatui-plbzq). Optional —
+     *  only scapes that play OUTSIDE the audio graph need it: a radio
+     *  stream's plain `<audio>` element mirrors `volume() × `its own gain
+     *  onto `el.volume`, refreshed on the lookahead tick, so the volume
+     *  slider and cross-tab mute reach it too. Hand-made test contexts may
+     *  omit it (the scape then reads full volume). */
+    volume?: () => number;
 }
 export interface ScapeInstance {
     /** Begin sounding at audio time `at` (usually ctx.currentTime). */

package/dist/components/AmbienceToggle.svelte

@@ -26,12 +26,18 @@
 	 *   - A playing (or paused) scape shows a now-playing block above the
 	 *     volume row (jatui-153tz): for a playlist — the track title, its
 	 *     composer · license attribution, an elapsed/total progress bar and a
-	 *     prev / play-pause / next transport (prev restarts the track when more
-	 *     than 3 s are in, else goes back one; play-pause freezes the station
-	 *     without closing the menu; next skips). Generative scapes (noise /
-	 *     focus) get the play/pause control only. The transport joins the
-	 *     menu's roving order; a paused row stays visible (its play button is
-	 *     the resume) and a stopped one hides.
+	 *     shuffle / prev / play-pause / next transport (shuffle is an
+	 *     aria-pressed IconButton, persisted per station and fresh-shuffled
+	 *     per session with no-repeat — jatui-plbzq; prev restarts the track
+	 *     when more than 3 s are in, else goes back one; play-pause freezes
+	 *     the station without closing the menu; next skips). Generative
+	 *     scapes (noise / focus) get the play/pause control only. A radio
+	 *     station registered with a public `streamUrl` (jatui-plbzq) gets the
+	 *     station name, a `Open station site` attribution link and
+	 *     play/pause — the stream is fetched by the browser from the station
+	 *     itself, never relayed. The transport joins the menu's roving order;
+	 *     a paused row stays visible (its play button is the resume) and a
+	 *     stopped one hides.
 	 *   - Playlists whose licence permits redistribution (jatui-0vxcu: CC0,
 	 *     public domain, CC-BY, CC-BY-SA — never NC/ND unless the manifest
 	 *     marks the track `downloadable: true`) also get a Download button
@@ -98,6 +104,14 @@
 		return `${track.title} — ${trackAttribution(track)}`;
 	}
 
+	/** The radio row's attribution href (jatui-plbzq): the scape's site url
+	 *  re-validated with `safeAmbienceHref` — the registry could be hostile
+	 *  on a remote tab too, and the leader is another tab, not a source of
+	 *  trust. Null hides the 'Open station site' link. */
+	export function radioSite(scape: RadioStreamScape | null | undefined): string | null {
+		return scape ? safeAmbienceHref(scape.href) : null;
+	}
+
 	/** "3:07" — m:ss for the now-playing row's elapsed/total (jatui-153tz). */
 	export function formatTrackTime(seconds: number | null | undefined): string {
 		if (
@@ -243,6 +257,7 @@
 	import { getMotionContext } from '../motion/level';
 	import { isAmbienceLink, safeAmbienceHref } from '../ambience/groups';
 	import { isPlaylistScape, type PlaylistState } from '../ambience/scapes/playlist';
+	import { isRadioScape, type RadioStreamScape, type RadioStreamState } from '../ambience/scapes/radio';
 	import {
 		isTrackDownloadable,
 		trackDownloadFilename
@@ -321,6 +336,10 @@
 	 *  now-playing row's progress bar. Null on plain/remote tabs without a
 	 *  local playing instance. */
 	let playlist = $state<PlaylistState | null>(null);
+	/** The current radio scape's live snapshot (jatui-plbzq) — its error
+	 *  line (a station that stalls or dies) and status. Null on remote tabs
+	 *  without a local playing instance. */
+	let radioState = $state<RadioStreamState | null>(null);
 	/** The shared player's now-playing line (jatui-lm1mf): published by the
 	 *  leader tab, so a remote tab shows the same track attribution without
 	 *  owning the playlist instance. Null on a plain engine. */
@@ -335,6 +354,9 @@
 	 *  download button reads this; null hides the button (not published, or
 	 *  the licence forbids redistribution). */
 	let sharedDownload = $state<SharedTrackDownload | null>(null);
+	/** The leader's published playlist shuffle state (jatui-plbzq) — a
+	 *  remote tab's Shuffle toggle reads this; null when unknown. */
+	let sharedShuffle = $state<boolean | null>(null);
 	/** True while a download fetch is in flight — the button shows its busy
 	 *  spinner and refuses re-entry. The fetch runs beside playback; nothing
 	 *  here touches the engine. */
@@ -367,13 +389,31 @@
 	 *  published state and routes transport commands to it. */
 	const isRemote = $derived(sharedRole === 'remote');
 	const currentIsPlaylist = $derived(isPlaylistScape(currentItem));
+	/** The current scape is a radio stream (jatui-plbzq): its now-playing
+	 *  row shows the station name + the 'Open station site' attribution
+	 *  link, and play/pause only — no tracks to skip, no download. */
+	const currentIsRadio = $derived(isRadioScape(currentItem));
+	/** The current radio scape, narrowed — carries the validated site url
+	 *  even on a remote tab (the registry is the same everywhere). */
+	const currentRadio = $derived(currentIsRadio ? (currentItem as unknown as RadioStreamScape) : null);
+	const radioSiteHref = $derived(radioSite(currentRadio));
+	/** The radio row's error line — leader/local only (a remote has no
+	 *  local instance to report through). */
+	const radioError = $derived(radioState?.status === 'error' ? (radioState.error ?? '') : '');
+	/** The Shuffle toggle's pressed state (jatui-plbzq): the playing
+	 *  playlist's own truth locally; the leader's published one remotely. */
+	const shufflePressed = $derived(
+		currentIsPlaylist ? (isRemote ? (sharedShuffle ?? playlist?.shuffle ?? false) : (playlist?.shuffle ?? false)) : false
+	);
 	/** The row exists while something is sounding or paused — a paused row
 	 *  must stay (its play button is how you resume); a stopped one hides. */
 	const showNowPlaying = $derived((playing || paused) && !!currentItem);
 	const npTitle = $derived(
-		isRemote
-			? (sharedTitle ?? '')
-			: (playlist?.track?.title ?? (currentIsPlaylist ? '' : (currentLabel ?? '')))
+		currentIsRadio
+			? (currentRadio?.label ?? '')
+			: isRemote
+				? (sharedTitle ?? '')
+				: (playlist?.track?.title ?? (currentIsPlaylist ? '' : (currentLabel ?? '')))
 	);
 	const npAttrib = $derived(
 		isRemote
@@ -470,6 +510,7 @@
 			sharedPosition = s.trackPosition;
 			sharedDuration = s.trackDuration;
 			sharedDownload = s.trackDownload ?? null;
+			sharedShuffle = s.trackShuffle;
 		});
 	});
 
@@ -505,11 +546,29 @@
 							license: t.license,
 							...(t.sourceUrl ? { sourceUrl: t.sourceUrl } : {})
 						}
-					: null
+					: null,
+				// The Shuffle toggle's truth (jatui-plbzq): published so a remote
+				// tab renders the leader's shuffle state.
+				s.shuffle
 			);
 		});
 	});
 
+	// The current scape is a radio stream (jatui-plbzq) → follow its state
+	// for the error line (a stream that stalls or dies). The row's station
+	// name and attribution link come from the registered item itself, so a
+	// remote tab needs no publication to render them.
+	$effect(() => {
+		const item = currentItem;
+		if (!isRadioScape(item)) {
+			radioState = null;
+			return;
+		}
+		return item.subscribe((s) => {
+			radioState = s;
+		});
+	});
+
 	// Breathing glyph: follow the engine's shared breath clock while playing,
 	// and only where ambient motion is allowed (getMotionContext().ambient is
 	// false under prefers-reduced-motion AND under data-motion="calm"). The
@@ -766,6 +825,21 @@
 		if (isPlaylistScape(currentItem)) currentItem.skip();
 	}
 
+	/** The Shuffle toggle (jatui-plbzq): flip the playing playlist's
+	 *  shuffle state — the per-station preference persists, and a session's
+	 *  order is freshly shuffled with recently-heard tracks last. A remote
+	 *  routes the command to the leader (its instance owns the running
+	 *  order and the persisted preference). */
+	function onShuffleClick() {
+		const next = !shufflePressed;
+		const e = engine as SharedAmbience;
+		if (isRemote && typeof e.shuffleTrack === 'function' && currentId) {
+			e.shuffleTrack(currentId, next);
+			return;
+		}
+		if (isPlaylistScape(currentItem)) currentItem.setShuffle(next);
+	}
+
 	/**
 	 * The download button (jatui-0vxcu). A cross-origin `<a download>` is
 	 * ignored by browsers, so the file is fetched to a Blob and saved through
@@ -1115,7 +1189,45 @@
 					{#if npTitle}
 						<p class="block truncate text-sm font-medium" title={npTitle}>{npTitle}</p>
 					{/if}
-					{#if npAttrib}
+					{#if currentIsRadio}
+						<!-- Radio (jatui-plbzq): the station's own site is the
+						     attribution — a real link, kept even though the stream
+						     now plays right here (it is fetched by the browser from
+						     the station, never relayed). A stream that stalls or
+						     dies says so instead of playing silence. -->
+						<div class="text-2xs mt-0.5 flex items-center gap-2">
+							{#if radioSiteHref}
+								<a
+									href={radioSiteHref}
+									target="_blank"
+									rel="noopener noreferrer"
+									tabindex="-1"
+									class="inline-flex min-w-0 items-center gap-1 text-primary
+										hover:underline focus-visible:underline"
+								>
+									<span class="truncate">Open station site</span>
+									<svg
+										xmlns="http://www.w3.org/2000/svg"
+										viewBox="0 0 24 24"
+										fill="none"
+										stroke="currentColor"
+										stroke-width="2"
+										stroke-linecap="round"
+										stroke-linejoin="round"
+										class="size-3 shrink-0"
+										aria-hidden="true"
+									>
+										<path d="M15 3h6v6" />
+										<path d="M10 14 21 3" />
+										<path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+									</svg>
+								</a>
+							{/if}
+							{#if radioError}
+								<span class="truncate text-error" title={radioError}>{radioError}</span>
+							{/if}
+						</div>
+					{:else if npAttrib}
 						<p class="text-2xs text-base-content/55 block truncate" title={npAttrib}>{npAttrib}</p>
 					{/if}
 					{#if npDuration > 0}
@@ -1136,6 +1248,43 @@
 						</div>
 					{/if}
 					<div class="mt-1.5 flex items-center justify-center gap-1">
+						{#if currentIsPlaylist}
+							<!-- Shuffle (jatui-plbzq): an aria-pressed toggle over the
+						     playlist's fresh-per-session order (recently-heard tracks
+						     last). Persisted per station; a remote routes the toggle
+						     to the leader. -->
+							<IconButton
+								label="Shuffle"
+								variant="ghost"
+								size="sm"
+								shape="circle"
+								tooltip="Shuffle"
+								tooltipPlacement="top"
+								pressed={shufflePressed}
+								tabindex={-1}
+								data-ambience-nav
+								onclick={onShuffleClick}
+							>
+								<svg
+									xmlns="http://www.w3.org/2000/svg"
+									viewBox="0 0 24 24"
+									fill="none"
+									stroke="currentColor"
+									stroke-width="2"
+									stroke-linecap="round"
+									stroke-linejoin="round"
+									class="size-4 {shufflePressed ? 'text-primary' : ''}"
+									aria-hidden="true"
+								>
+									<!-- shuffle, lucide geometry -->
+									<path d="m18 14 4 4-4 4" />
+									<path d="m18 2 4 4-4 4" />
+									<path d="M2 18h1.973a4 4 0 0 0 3.3-1.7l5.454-8.6a4 4 0 0 1 3.3-1.7H22" />
+									<path d="M2 6h1.972a4 4 0 0 1 3.6 2.2" />
+									<path d="M22 18h-6.041a4 4 0 0 1-3.3-1.8l-.359-.45" />
+								</svg>
+							</IconButton>
+						{/if}
 						{#if currentIsPlaylist}
 							<button
 								type="button"