@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/ui/App.js

@@ -1,11 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { fileURLToPath } from 'node:url';
-import { Box, Text, useApp, useStdin, useStdout, useWindowSize } from 'ink';
+import { Box, Text, useApp, useIsScreenReaderEnabled, useStdin, useStdout, useWindowSize } from 'ink';
 import { ProviderManager } from '../providers/provider-manager.js';
-import { PlayerController } from '../player/player-controller.js';
-import { playbackBackendInstallHint, playbackBackendLabel } from '../player/backend-install.js';
+import { PlaybackOutputError, PlayerController } from '../player/player-controller.js';
+import { airPlayLocalDeviceLabel, playbackBackendInstallHint, playbackBackendLabel } from '../player/backend-install.js';
 import { JsonLibraryStore, stationKey } from '../storage/store.js';
+import { LibraryRepository } from '../storage/repository.js';
+import { RadioEngine } from '../player/radio-engine.js';
+import { TuiPlayer, TuiRadioEngine } from '../agent/tui-session.js';
 import { defaultAgentControlSettings } from '../types.js';
 import { nextReceiverStyle, nextTheme, textDim, textMuted, themeAccent } from './theme.js';
 import { DisplayContext, resolveDisplayMode } from './display-context.js';
@@ -21,29 +24,31 @@ import { useAppInput } from './use-app-input.js';
 import { useCommandExecutor } from './use-command-executor.js';
 import { isAirPlayCodePromptActive } from './screens/AirPlayCodeScreen.js';
 import { isAirPlayBackendAvailable } from './airplay-settings.js';
+import { networkPolicy } from '../platform/network.js';
 import { audioOutputLabel, resolvedAudioOutput } from './audio-output.js';
 import { copyToClipboard, openExternal } from './system-actions.js';
+import { safeExternalHttpUrl, safeMediaTarget, sanitizeTerminalText } from '../safety.js';
 import { appVersion } from '../version.js';
 import { automaticUpdateChecksAllowed, checkForUpdate, installUpdate, shouldCheckForUpdate, updateAvailableForVersion, updateCommandForInstall } from '../update-check.js';
-import { helpItemCount } from './help-content.js';
+import { airPlayPolicy, airPlaySetupRequiredMessage } from '../player/airplay-policy.js';
+import { helpItemCountForAirPlay } from './help-content.js';
 import { EXIT_CONFIRMATION_MS, ctrlCExitDecision } from './exit-confirmation.js';
 import { createAlarmTuiService, serializeAlarmTuiService } from './alarm-tui-service.js';
 import { useAlarmTui } from './use-alarm-tui.js';
 import { toAsciiSafe } from './ascii.js';
 import { registerTuiPresence } from '../alarms/tui-presence.js';
 import { configureMcpIntegrations } from '../agent/mcp-install.js';
-import { startRadioSession } from '../agent/session.js';
-import { activeTabForScreen, addMediaKeyBinding, applyStationFilters, clamp, clampVolume, defaultExploreCursor, formatExploreCursor, formatFilterLabel, formatTimeLeft, initialStationContexts, mediaActionLabel, moveExploreCursor as shiftExploreCursor, nextSleepTimerMinutes, normalizeMediaKeyBindings, shouldSkipAfterTuneError, stationApproximateTime, stationContextKeyForScreen, topTabs } from './app-state.js';
+import { allowedRadioSessionSettings, resolveDesktopTransport, serializeRadioCommands, startRadioSession } from '../agent/session.js';
+import { desktopMediaPolicy, startDesktopMediaControls } from '../platform/desktop-media.js';
+import { activeTabForScreen, addMediaKeyBinding, applyStationFilters, clamp, clampVolume, defaultExploreCursor, formatExploreCursor, formatFilterLabel, formatTimeLeft, initialStationContexts, mediaActionLabel, moveExploreCursor as shiftExploreCursor, nextSleepTimerMinutes, stationApproximateTime, stationContextKeyForScreen, topTabs } from './app-state.js';
 import { ReceiverAnimationProvider } from './receiver-animation.js';
 import { VersionIndicator, versionIndicatorWidth } from './components/VersionIndicator.js';
 const LOADING_SPINNER_MS = 120;
-const VISUALIZER_MESSAGE_MS = 4500;
-const LISTENING_HEARTBEAT_MS = 30_000;
+const TRANSIENT_NOTICE_MS = 4500;
 const COUNTRY_STATIONS_PAGE_SIZE = 120;
 const COUNTRY_STATIONS_LOAD_AHEAD = 12;
 const SEARCH_RESULTS_PAGE_SIZE = 90;
 const SEARCH_RESULTS_LOAD_AHEAD = 12;
-const BROKEN_STREAM_AUTO_SKIP_DELAY_MS = 1000;
 const settingToggleLabel = {
     resumeOnLaunch: 'Resume on launch',
     transparentBackground: 'Transparent background',
@@ -52,33 +57,40 @@ const settingToggleLabel = {
     mouseSupport: 'Mouse and trackpad scrolling',
     automaticUpdateChecks: 'Automatic update checks'
 };
-export function App({ store: providedStore, providers: providedProviders, alarmService: providedAlarmService, alarmPreview, initialAgentCommand, mcpConfigurator = configureMcpIntegrations, updateChecker = checkForUpdate }) {
+export function App({ store: providedStore, providers: providedProviders, alarmService: providedAlarmService, alarmPreview, initialAgentCommand, mcpConfigurator = configureMcpIntegrations, updateChecker = checkForUpdate, platform = process.platform, playbackSession, playbackRecoveryWarning }) {
     const { exit } = useApp();
     const { stdin } = useStdin();
     const { stdout } = useStdout();
     const { columns, rows } = useWindowSize();
-    const store = useMemo(() => providedStore ?? new JsonLibraryStore(), [providedStore]);
+    const screenReader = useIsScreenReaderEnabled();
+    const store = useMemo(() => new LibraryRepository(providedStore ?? new JsonLibraryStore(), { worker: !providedStore }), [providedStore]);
     const providers = useMemo(() => providedProviders ?? new ProviderManager(), [providedProviders]);
     const alarmService = useMemo(() => providedAlarmService ? serializeAlarmTuiService(providedAlarmService) : createAlarmTuiService(), [providedAlarmService]);
     const installedVersion = useMemo(() => appVersion(), []);
-    const [library, setLibrary] = useState(() => store.snapshot());
+    const [library, setLibrary] = useState(() => localSessionLibrary(store.snapshot(), platform, playbackSession?.status.tui?.selectionRequired));
     const settingsRef = useRef(library.settings);
-    settingsRef.current = library.settings;
-    const player = useMemo(() => new PlayerController(() => settingsRef.current), []);
+    const settingsQueueRef = useRef(Promise.resolve());
+    const player = useMemo(() => playbackSession ? new TuiPlayer(playbackSession, () => settingsRef.current)
+        : new PlayerController(() => settingsRef.current, { platform, arch: process.arch, env: platform === process.platform ? process.env : {} }), [platform, playbackSession]);
     const [playback, setPlayback] = useState(() => player.getState());
     const [availableBackends, setAvailableBackends] = useState(() => player.detectedBackends());
+    const airPlay = airPlayPolicy(library.settings, { platform });
+    const airPlaySupported = airPlay.enabled;
+    const airPlayUnavailableMessage = airPlay.enabled ? (platform === 'linux' ? airPlaySetupRequiredMessage : 'AirPlay is not ready on this install. Run radiocli doctor.') : airPlay.message;
     const [availableAirPlayDevices, setAvailableAirPlayDevices] = useState(() => player.detectedAirPlayDevices());
-    const [screen, setScreen] = useState('home');
+    const [screen, setScreen] = useState(playbackSession?.status.station ? 'now-playing' : 'home');
     const [selected, setSelected] = useState(0);
     const [settingsPage, setSettingsPage] = useState('root');
     const [message, setMessage] = useState(null);
+    const [persistenceWarning, setPersistenceWarning] = useState(null);
+    const [presenceWarning, setPresenceWarning] = useState(playbackRecoveryWarning ?? null);
     const [footerMessage, setFooterMessage] = useState(null);
     const [countries, setCountries] = useState([]);
     const [countryFilter, setCountryFilter] = useState('');
     const [editingCountryFilter, setEditingCountryFilter] = useState(false);
     const [loadingCountries, setLoadingCountries] = useState(false);
     const [stationContexts, setStationContexts] = useState(initialStationContexts);
-    const [loadingStations, setLoadingStations] = useState(false);
+    const [loadingStationContexts, setLoadingStationContexts] = useState({});
     const [searchQuery, setSearchQuery] = useState('');
     const [editingSearch, setEditingSearch] = useState(true);
     const [playingStation, setPlayingStation] = useState(null);
@@ -92,20 +104,50 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     const [commandText, setCommandText] = useState('');
     const [airPlayCode, setAirPlayCode] = useState('');
     const [filters, setFilters] = useState({ codec: null, language: null, minBitrate: null });
-    const [sleepUntil, setSleepUntil] = useState(null);
+    const [sleepUntil, setSleepUntilState] = useState(playbackSession?.status.tui?.sleepUntil ?? null);
+    const setSleepUntil = useCallback((until) => {
+        if (playbackSession)
+            void playbackSession.call({ type: 'tui-sleep', until }).catch(error => setMessage(sanitizeTerminalText(error instanceof Error ? error.message : String(error)) ?? 'Could not update the sleep timer.'));
+        else
+            setSleepUntilState(until);
+    }, [playbackSession]);
     const [showDiagnostics, setShowDiagnostics] = useState(false);
     const [capturingTransportAction, setCapturingTransportAction] = useState(null);
+    const reportActionError = useCallback((error) => {
+        setMessage(sanitizeTerminalText(error instanceof Error ? error.message : String(error)) ?? 'Could not complete this action.');
+    }, []);
+    // Optional history cannot change the result of playback or navigation. Keep
+    // its warning until an explicit save succeeds; a no-op checkpoint proves nothing.
+    const persistLibrary = useCallback(async (write) => {
+        try {
+            const nextLibrary = localSessionLibrary(await write(), platform, player.airPlaySelectionRequired());
+            setLibrary(nextLibrary);
+            return nextLibrary;
+        }
+        catch (error) {
+            const detail = sanitizeTerminalText(error instanceof Error ? error.message : String(error));
+            setPersistenceWarning(`Library not saved. Set RADIOCLI_HOME to a writable directory.${detail ? ` ${detail}` : ''}`);
+            return undefined;
+        }
+    }, [platform, player]);
+    const engine = useMemo(() => playbackSession ? new TuiRadioEngine(playbackSession) : new RadioEngine(player, providers, store, () => settingsRef.current, saved => {
+        setLibrary(localSessionLibrary(saved, platform, player.airPlaySelectionRequired()));
+    }), [player, providers, store, platform, playbackSession]);
     const announcedUpdateRef = useRef(false);
     const automaticUpdateCheckStartedRef = useRef(false);
     const installingUpdateRef = useRef(false);
     const configuringMcpRef = useRef(false);
     const displayStationsRef = useRef([]);
-    const playbackQueueRef = useRef(null);
+    const playbackQueueRef = useRef(playbackSession?.status.queue.length
+        ? { title: 'Recovered station list', sourceScreen: 'now-playing', sourceContextKey: null, stations: playbackSession.status.queue } : null);
+    const focusNowPlayingRef = useRef(playbackSession?.status.tui?.focusNowPlaying ?? 0);
     const lastRawTransportAtRef = useRef(0);
-    const loadingStationsRef = useRef(false);
+    const loadingStationContextsRef = useRef({});
     const countryPageRequestRef = useRef(null);
     const searchPageRequestRef = useRef(null);
-    const playStationRef = useRef(() => undefined);
+    const activeSearchRef = useRef(null);
+    const searchContextFingerprintRef = useRef(null);
+    const searchFingerprint = JSON.stringify([filters.codec, filters.language, filters.minBitrate, Boolean(library.settings.enableRadioGarden)]);
     const screenRef = useRef(screen);
     const selectedRef = useRef(selected);
     const settingsPageRef = useRef(settingsPage);
@@ -124,16 +166,45 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     const helpReturnScreenRef = useRef('home');
     const countriesLoadAttemptedRef = useRef(false);
     const tuneRequestRef = useRef(0);
+    const outputCancellationRef = useRef(0);
+    const pendingOutputChangesRef = useRef(0);
     const searchRequestRef = useRef(0);
     const countryRequestRef = useRef(0);
     const nearbyRequestRef = useRef(0);
-    const skipBrokenTimerRef = useRef(null);
+    const discoveryAbortRef = useRef({});
+    const beginDiscovery = useCallback((key) => {
+        discoveryAbortRef.current[key]?.abort();
+        const controller = new AbortController();
+        discoveryAbortRef.current[key] = controller;
+        return controller.signal;
+    }, []);
+    const cancelPendingTune = useCallback(() => {
+        tuneRequestRef.current += 1;
+        outputCancellationRef.current += 1;
+        engine.cancel();
+    }, [engine]);
     const volumeRequestRef = useRef(0);
     const agentHandlerRef = useRef(async () => {
         throw new Error('RadioCLI is still starting.');
     });
+    const dispatchOwnerCommand = useMemo(() => serializeRadioCommands((command, signal) => agentHandlerRef.current(command, signal), { responsive: true }), []);
+    const desktopPolicy = useMemo(() => desktopMediaPolicy(library.settings, { platform }), [library.settings.desktopMediaControls, platform]);
+    const desktopSuspendedRef = useRef(false);
+    const desktopMediaRef = useRef(null);
+    const activeAlarmRef = useRef(false);
+    const [controlSessionReady, setControlSessionReady] = useState(Boolean(playbackSession));
+    const showTransientMessage = useCallback((nextMessage) => {
+        if (transientMessageTimerRef.current) {
+            clearTimeout(transientMessageTimerRef.current);
+        }
+        setMessage(nextMessage);
+        transientMessageTimerRef.current = setTimeout(() => {
+            setMessage(currentMessage => currentMessage === nextMessage ? null : currentMessage);
+            transientMessageTimerRef.current = null;
+        }, TRANSIENT_NOTICE_MS);
+    }, []);
     const theme = library.settings.theme;
-    const displayMode = useMemo(() => resolveDisplayMode(library.settings), [library.settings.transparentBackground, library.settings.asciiMode, library.settings.reduceMotion]);
+    const displayMode = useMemo(() => resolveDisplayMode(library.settings, process.env, { screenReader, isTTY: Boolean(stdout.isTTY), colorDepth: stdout.getColorDepth?.() }), [library.settings.transparentBackground, library.settings.asciiMode, library.settings.reduceMotion, screenReader, stdout]);
     const favoriteKeys = useMemo(() => new Set(library.favorites.map(stationKey)), [library.favorites]);
     const diagnostics = player.diagnostics();
     const filterLabel = formatFilterLabel(filters);
@@ -156,10 +227,10 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     screenRef.current = screen;
     selectedRef.current = selected;
     settingsPageRef.current = settingsPage;
-    loadingStationsRef.current = loadingStations;
     stationContextsRef.current = activeStationContexts;
     exploreCursorRef.current = exploreCursor;
     const renderedStationContextKey = stationContextKeyForScreen(screen);
+    const loadingStations = renderedStationContextKey ? Boolean(loadingStationContexts[renderedStationContextKey]) : false;
     const activeStationContextKey = renderedStationContextKey ?? lastStationContextKeyRef.current;
     const stationContext = activeStationContexts[activeStationContextKey];
     const stationCounts = useMemo(() => ({
@@ -186,8 +257,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         'alarm-ringing': 0,
         'airplay-settings': 0,
         'airplay-code': 1,
-        settings: settingsItemsForPage(settingsPage).length,
-        help: helpItemCount
+        settings: settingsItemsForPage(settingsPage, airPlaySupported).length,
+        help: helpItemCountForAirPlay(airPlaySupported)
     });
     itemCountsRef.current = {
         home: homeItems.length,
@@ -206,8 +277,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         'alarm-ringing': 0,
         'airplay-settings': availableAirPlayDevices.length,
         'airplay-code': 1,
-        settings: settingsItemsForPage(settingsPage).length,
-        help: helpItemCount
+        settings: settingsItemsForPage(settingsPage, airPlaySupported).length,
+        help: helpItemCountForAirPlay(airPlaySupported)
     };
     const displayStations = useMemo(() => applyStationFilters(stationContext.stations, filters), [filters, stationContext.stations]);
     displayStationsRef.current = displayStations;
@@ -222,52 +293,69 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         Boolean(isAirPlayBackendAvailable(availableBackends) && selectedAirPlayDevice?.requiresPassword && !selectedAirPlayDevice.local);
     const layout = computeTerminalLayout(columns, rows, footerRows);
     const frameWidth = layout.frameWidth;
-    const mouseReportingActive = !commandMode &&
+    const mouseReportingActive = !displayMode.screenReader &&
+        process.env.TERM?.toLowerCase() !== 'dumb' &&
+        !commandMode &&
         !capturingTransportAction &&
         !editingCountryFilter &&
         shouldEnableMouseReporting(screen, itemCountsRef.current[screen] ?? 0, mouseVisibleRows(screen, layout), library.settings.mouseSupport !== false);
-    useEffect(() => player.onChange(setPlayback), [player]);
-    useEffect(() => stdin.isTTY ? registerTuiPresence() : undefined, [stdin]);
-    const playingStationRef = useRef(null);
-    playingStationRef.current = playingStation;
-    const activeListeningStationRef = useRef(null);
-    const lastRecordedTrackRef = useRef(null);
     useEffect(() => {
-        const station = playingStationRef.current;
-        const isAudible = playback.state === 'playing' && playback.ready && station;
-        if (isAudible) {
-            const key = stationKey(station);
-            if (activeListeningStationRef.current !== key) {
-                activeListeningStationRef.current = key;
-                setLibrary(store.startListeningSession(station));
-            }
+        if (!stdin.isTTY)
             return;
+        try {
+            const unregister = registerTuiPresence();
+            return () => {
+                try {
+                    unregister();
+                }
+                catch {
+                    console.error('RadioCLI could not remove its alarm-control presence marker. Stale markers are checked on the next launch.');
+                }
+            };
         }
-        if (activeListeningStationRef.current) {
-            activeListeningStationRef.current = null;
-            setLibrary(store.finishActiveListeningSession());
-        }
-    }, [playback.ready, playback.state, playingStation, store]);
-    useEffect(() => {
-        if (playback.state !== 'playing' || !playback.ready || !playingStation) {
-            return;
+        catch {
+            setPresenceWarning([playbackRecoveryWarning, 'Alarm controls cannot register this terminal in the runtime directory. Browsing and playback remain available.'].filter(Boolean).join(' '));
         }
-        const timer = setInterval(() => {
-            setLibrary(store.checkpointActiveListeningSession());
-        }, LISTENING_HEARTBEAT_MS);
-        return () => clearInterval(timer);
-    }, [playback.ready, playback.state, playingStation, store]);
-    useEffect(() => player.onMetadata(metadata => {
-        setNowPlaying(metadata);
-        const station = playingStationRef.current;
-        if (station && metadata.title) {
-            const trackKey = `${stationKey(station)}:${metadata.title}`;
-            if (lastRecordedTrackRef.current === trackKey)
-                return;
-            lastRecordedTrackRef.current = trackKey;
-            setLibrary(store.recordTrack(station, metadata.title));
+    }, [stdin, playbackRecoveryWarning]);
+    const playingStationRef = useRef(null);
+    playingStationRef.current = playingStation;
+    useEffect(() => engine.onChange(current => {
+        setPlayback(current.playback);
+        playingStationRef.current = current.station;
+        setPlayingStation(current.station);
+        setTuningStation(current.tuningStation);
+        setNowPlaying(current.nowPlaying);
+        if (playbackSession) {
+            setSleepUntilState(playbackSession.status.tui?.sleepUntil ?? null);
+            const previous = playbackQueueRef.current;
+            playbackQueueRef.current = current.queue.length ? { ...(previous ?? { title: 'Current station list', sourceScreen: 'now-playing', sourceContextKey: null }), stations: current.queue } : null;
+            const focus = playbackSession.status.tui?.focusNowPlaying ?? 0;
+            if (focus !== focusNowPlayingRef.current) {
+                focusNowPlayingRef.current = focus;
+                screenRef.current = 'now-playing';
+                setScreen('now-playing');
+            }
         }
-    }), [player, store]);
+        if (current.warning)
+            setPersistenceWarning(current.warning.replace('Listening history was not saved', 'Library not saved'));
+        if (current.message)
+            setMessage(current.message);
+    }), [engine, playbackSession]);
+    useEffect(() => {
+        const off = store.subscribe(saved => {
+            const next = localSessionLibrary(saved, platform, player.airPlaySelectionRequired());
+            settingsRef.current = next.settings;
+            setLibrary(next);
+        });
+        const offError = store.onError(error => setPersistenceWarning(`Library could not refresh: ${error.message}`));
+        return () => {
+            off();
+            offError();
+            // Normal shutdown closes the owner explicitly. An unexpected render
+            // failure must release this view's storage without stopping its audio.
+            void (playbackSession ? store.close() : engine.close().finally(() => store.close())).catch(() => undefined);
+        };
+    }, [store, engine, platform, player, playbackSession]);
     useEffect(() => {
         if (!stdout.isTTY || !mouseReportingActive) {
             return;
@@ -285,7 +373,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     }, [renderedStationContextKey, screen, selected]);
     useEffect(() => {
         if (footerPlayback.state !== 'loading' ||
-            library.settings.reduceMotion ||
+            displayMode.reduceMotion ||
             process.env.RADIOCLI_DISABLE_ANIMATION === '1' ||
             process.env.RADIO_ATLAS_DISABLE_ANIMATION === '1') {
             setSpinnerFrame(0);
@@ -293,7 +381,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
         const timer = setInterval(() => setSpinnerFrame(value => (value + 1) % 1000), LOADING_SPINNER_MS);
         return () => clearInterval(timer);
-    }, [footerPlayback.state, library.settings.reduceMotion]);
+    }, [footerPlayback.state, displayMode.reduceMotion]);
     useEffect(() => {
         if ((screen === 'countries' || screen === 'map') &&
             countries.length === 0 &&
@@ -309,6 +397,14 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
     }, [countries.length, loadingCountries, providers, screen]);
     useEffect(() => () => {
+        exploreRequestRef.current += 1;
+        countryRequestRef.current += 1;
+        searchRequestRef.current += 1;
+        nearbyRequestRef.current += 1;
+        for (const controller of Object.values(discoveryAbortRef.current))
+            controller.abort();
+        countryPageRequestRef.current = null;
+        searchPageRequestRef.current = null;
         if (exploreMoveTimerRef.current) {
             clearTimeout(exploreMoveTimerRef.current);
         }
@@ -318,41 +414,41 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         if (transientFooterMessageTimerRef.current) {
             clearTimeout(transientFooterMessageTimerRef.current);
         }
-        if (skipBrokenTimerRef.current) {
-            clearTimeout(skipBrokenTimerRef.current);
-        }
     }, []);
     useEffect(() => {
         setSelected(value => clamp(value, currentItemCount(screen) - 1));
     }, [availableAirPlayDevices.length, displayStations.length, filteredCountries.length, screen]);
     useEffect(() => {
+        if (playbackSession)
+            return;
         if (!sleepUntil) {
             return;
         }
         const delayMs = sleepUntil - Date.now();
         if (delayMs <= 0) {
-            tuneRequestRef.current += 1;
-            setLibrary(store.finishActiveListeningSession());
-            void player.stop();
+            cancelPendingTune();
+            void engine.stop({ retainSelection: true }).catch(reportActionError);
             setSleepUntil(null);
             return;
         }
         const timer = setTimeout(() => {
-            tuneRequestRef.current += 1;
-            setLibrary(store.finishActiveListeningSession());
-            void player.stop();
+            cancelPendingTune();
+            void engine.stop({ retainSelection: true }).catch(reportActionError);
             setSleepUntil(null);
         }, delayMs);
         return () => clearTimeout(timer);
-    }, [player, sleepUntil, store]);
+    }, [cancelPendingTune, engine, reportActionError, sleepUntil, playbackSession, setSleepUntil]);
     useEffect(() => {
         const backends = player.refreshDetectedBackends();
         setAvailableBackends(backends);
-        void player.refreshAirPlayDevices().then(setAvailableAirPlayDevices).catch(() => setAvailableAirPlayDevices([]));
+        const network = networkPolicy();
+        if (platform === 'darwin' && airPlaySupported && !network.offline && !network.lowBandwidth) {
+            void player.refreshAirPlayDevices().then(setAvailableAirPlayDevices).catch(() => setAvailableAirPlayDevices([]));
+        }
         if (backends.length === 0) {
             setMessage(`No playback backend found. ${playbackBackendInstallHint()}`);
         }
-    }, [player]);
+    }, [airPlaySupported, platform, player]);
     const refreshProviderHealth = useCallback(() => {
         providers.health(settingsRef.current).then(setProviderHealth).catch(() => setProviderHealth({}));
     }, [providers]);
@@ -361,9 +457,9 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     }, [refreshProviderHealth]);
     const refreshUpdateCheck = useCallback(async () => {
         const updateCheck = await updateChecker({ currentVersion: installedVersion });
-        setLibrary(store.updateCheckState(updateCheck));
+        persistLibrary(() => store.updateCheckState(updateCheck));
         return updateCheck;
-    }, [installedVersion, store, updateChecker]);
+    }, [installedVersion, persistLibrary, store, updateChecker]);
     useEffect(() => {
         if (automaticUpdateCheckStartedRef.current ||
             !automaticUpdateChecksAllowed(library.settings.automaticUpdateChecks !== false)) {
@@ -379,51 +475,93 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 announcedUpdateRef.current = true;
                 setMessage(`Update available: v${updateCheck.latestVersion} · run :update`);
             }
+        }).catch(error => {
+            if (!cancelled)
+                reportActionError(error);
         });
         return () => {
             cancelled = true;
         };
-    }, [library.settings.automaticUpdateChecks, refreshUpdateCheck]);
+    }, [library.settings.automaticUpdateChecks, refreshUpdateCheck, reportActionError]);
     const setStationContextFor = useCallback((key, context) => {
+        stationContextsRef.current = { ...stationContextsRef.current, [key]: context };
         setStationContexts(current => ({ ...current, [key]: context }));
     }, []);
+    const setStationLoading = useCallback((key, loading) => {
+        if (loadingStationContextsRef.current[key] === loading)
+            return;
+        loadingStationContextsRef.current[key] = loading;
+        setLoadingStationContexts(current => ({ ...current, [key]: loading }));
+    }, []);
     const stationMatches = useCallback((left, right) => stationKey(left) === stationKey(right), []);
     const queueContainsStation = useCallback((queue, station) => Boolean(queue?.stations.some(item => stationMatches(item, station))), [stationMatches]);
-    const updateSettings = useCallback((settings) => {
-        const nextLibrary = store.updateSettings(settings);
-        settingsRef.current = nextLibrary.settings;
-        setLibrary(nextLibrary);
-        return nextLibrary;
-    }, [store]);
+    const updateSettings = useCallback((update) => {
+        // Evaluate relative inputs after the preceding save has acknowledged. React
+        // may still be rendering that save, so the committed ref is authoritative.
+        const operation = settingsQueueRef.current.then(async () => {
+            const settings = typeof update === 'function' ? update(settingsRef.current) : update;
+            const saved = await store.updateSettings(settings);
+            if (settings.preferredBackend === 'airplay' && settings.preferredAirPlayDevice) {
+                // Receiver consent belongs to this acknowledged selection. Publish its
+                // ID to the player before applying the Linux session output overlay.
+                settingsRef.current = saved.settings;
+                await player.selectAirPlayDevice(settings.preferredAirPlayDevice);
+            }
+            if (settings.preferredBackend && settings.preferredBackend !== 'airplay')
+                await player.selectAirPlayDevice(null);
+            const nextLibrary = localSessionLibrary(saved, platform, player.airPlaySelectionRequired());
+            if (settings.enableNearbyLocation === false) {
+                nearbyRequestRef.current += 1;
+                discoveryAbortRef.current.nearby?.abort();
+                setStationLoading('nearby', false);
+            }
+            settingsRef.current = nextLibrary.settings;
+            setLibrary(nextLibrary);
+            setPersistenceWarning(null);
+            engine.clearWarning();
+            return nextLibrary;
+        });
+        settingsQueueRef.current = operation.then(() => undefined, () => undefined);
+        // Keyboard callbacks can intentionally fire and forget; awaited callers still
+        // receive the original rejection and never acknowledge an uncommitted save.
+        void operation.catch(reportActionError);
+        return operation;
+    }, [engine, platform, player, reportActionError, setStationLoading, store]);
     useEffect(() => {
         if (!selectedAirPlayDevice?.local || settingsRef.current.preferredBackend !== 'airplay') {
             return;
         }
         const preferredBackend = preferredLocalPlaybackBackend(availableBackends);
         if (!preferredBackend) {
-            setMessage(`${selectedAirPlayDevice.name} is this Mac. Install mpv to use local playback instead of AirPlay.`);
+            setMessage(`${selectedAirPlayDevice.name} is ${airPlayLocalDeviceLabel(platform)}. Install mpv to use local playback instead of AirPlay.`);
             return;
         }
-        updateSettings({ preferredBackend });
-        setMessage(`${selectedAirPlayDevice.name} is this Mac. Audio output: ${audioOutputLabel(preferredBackend)}.`);
-    }, [availableBackends, selectedAirPlayDevice, updateSettings]);
-    const updateMediaKeys = useCallback((mediaKeys) => {
-        updateSettings({ mediaKeys: normalizeMediaKeyBindings(mediaKeys) });
-    }, [updateSettings]);
+        let changed = false;
+        void updateSettings(current => {
+            if (current.preferredBackend !== 'airplay' || current.preferredAirPlayDevice !== selectedAirPlayDevice.id)
+                return {};
+            changed = true;
+            return { preferredBackend };
+        }).then(() => {
+            if (changed)
+                setMessage(`${selectedAirPlayDevice.name} is ${airPlayLocalDeviceLabel(platform)}. Audio output: ${audioOutputLabel(preferredBackend)}.`);
+        }).catch(() => undefined);
+    }, [availableBackends, platform, selectedAirPlayDevice, updateSettings]);
     const beginLearningTransportKey = useCallback((action) => {
         setCapturingTransportAction(action);
         setMessage(`Press a key for ${mediaActionLabel(action)}. Esc cancels.`);
     }, []);
     const resetLearnedTransportKeys = useCallback(() => {
-        updateMediaKeys({ previous: [], playPause: [], next: [] });
-        setMessage('Learned media keys reset. Built-in fallbacks still work.');
-    }, [updateMediaKeys]);
+        void updateSettings({ mediaKeys: { previous: [], playPause: [], next: [] } })
+            .then(() => setMessage('Learned media keys reset. Built-in fallbacks still work.'))
+            .catch(() => undefined);
+    }, [updateSettings]);
     const saveLearnedTransportKey = useCallback((action, input) => {
-        const mediaKeys = addMediaKeyBinding(settingsRef.current.mediaKeys, action, input);
-        updateMediaKeys(mediaKeys);
         setCapturingTransportAction(null);
-        setMessage(`Learned ${mediaActionLabel(action)} key.`);
-    }, [updateMediaKeys]);
+        void updateSettings(current => ({ mediaKeys: addMediaKeyBinding(current.mediaKeys, action, input) }))
+            .then(() => setMessage(`Learned ${mediaActionLabel(action)} key.`))
+            .catch(() => undefined);
+    }, [updateSettings]);
     const go = useCallback((next, options = {}) => {
         if (next === 'help' && screenRef.current !== 'help') {
             helpReturnScreenRef.current = screenRef.current;
@@ -437,27 +575,30 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             screenRef.current !== 'airplay-code') {
             settingsPageRef.current = 'root';
             setSettingsPage('root');
-            itemCountsRef.current.settings = settingsItemsForPage('root').length;
+            itemCountsRef.current.settings = settingsItemsForPage('root', airPlaySupported).length;
             selectedByScreenRef.current.settings = selectedBySettingsPageRef.current.root ?? 0;
         }
         selectedByScreenRef.current[screenRef.current] = selectedRef.current;
         const remembered = selectedByScreenRef.current[destination] ?? 0;
-        const nextSelection = options.resetSelection ? 0 : remembered;
+        const nextSelection = clamp(options.resetSelection ? 0 : remembered, (itemCountsRef.current[destination] ?? 0) - 1);
+        // Input can arrive in one batch before React renders the next screen.
+        screenRef.current = destination;
+        selectedRef.current = nextSelection;
         setScreen(destination);
-        setSelected(clamp(nextSelection, (itemCountsRef.current[destination] ?? 0) - 1));
+        setSelected(nextSelection);
         if (options.clearMessage !== false) {
             setMessage(null);
         }
-    }, []);
+    }, [airPlaySupported]);
     const openSettingsPage = useCallback((next) => {
         selectedBySettingsPageRef.current[settingsPageRef.current] = selectedRef.current;
         settingsPageRef.current = next;
         setSettingsPage(next);
-        const nextSelection = clamp(selectedBySettingsPageRef.current[next] ?? 0, settingsItemsForPage(next).length - 1);
+        const nextSelection = clamp(selectedBySettingsPageRef.current[next] ?? 0, settingsItemsForPage(next, airPlaySupported).length - 1);
         selectedRef.current = nextSelection;
         setSelected(nextSelection);
         setMessage(null);
-    }, []);
+    }, [airPlaySupported]);
     const closeSettingsPage = useCallback(() => {
         if (settingsPageRef.current === 'root') {
             go('home');
@@ -466,9 +607,13 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         openSettingsPage('root');
     }, [go, openSettingsPage]);
     const openAirPlayCode = useCallback(() => {
+        if (!airPlaySupported) {
+            showTransientMessage(airPlayUnavailableMessage);
+            return;
+        }
         setAirPlayCode('');
         go('airplay-code', { resetSelection: true, clearMessage: false });
-    }, [go]);
+    }, [airPlaySupported, airPlayUnavailableMessage, go, showTransientMessage]);
     useEffect(() => {
         if (isAirPlayCodePromptActive(playback) && screenRef.current !== 'airplay-code') {
             openAirPlayCode();
@@ -476,13 +621,18 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     }, [openAirPlayCode, playback.backend, playback.message]);
     const shutdown = useCallback(() => {
         tuneRequestRef.current += 1;
-        store.finishActiveListeningSession();
-        player.stop().finally(exit);
-    }, [exit, player, store]);
+        desktopSuspendedRef.current = true;
+        desktopMediaRef.current?.close();
+        cancelPendingTune();
+        void engine.close().finally(() => store.close()).catch(reportActionError).finally(exit);
+    }, [cancelPendingTune, engine, exit, reportActionError, store]);
     useEffect(() => {
         const finishForSignal = () => {
-            store.finishActiveListeningSession();
-            void player.stop().finally(() => process.exit(0));
+            tuneRequestRef.current += 1;
+            desktopSuspendedRef.current = true;
+            desktopMediaRef.current?.close();
+            cancelPendingTune();
+            void engine.close().finally(() => store.close()).catch(reportActionError).finally(() => process.exit(0));
         };
         process.once('SIGTERM', finishForSignal);
         process.once('SIGHUP', finishForSignal);
@@ -490,19 +640,14 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             process.off('SIGTERM', finishForSignal);
             process.off('SIGHUP', finishForSignal);
         };
-    }, [player, store]);
-    const showStationContext = useCallback((context, next = 'stations', options = {}) => {
-        setStationContextFor(stationContextKeyForScreen(next) ?? 'stations', context);
-        go(next, { resetSelection: options.resetSelection ?? true, clearMessage: options.clearMessage });
-    }, [go, setStationContextFor]);
-    const loadExploreAt = useCallback(async (cursor, options = {}) => {
+    }, [cancelPendingTune, engine, reportActionError, store]);
+    const loadExploreAt = useCallback(async (cursor) => {
         const requestId = exploreRequestRef.current + 1;
         exploreRequestRef.current = requestId;
-        setLoadingStations(true);
-        setMessage(null);
-        if (screenRef.current !== 'explore') {
-            go('explore', { resetSelection: options.resetSelection ?? true, clearMessage: options.clearMessage });
-        }
+        const signal = beginDiscovery('explore');
+        setStationLoading('explore', true);
+        if (screenRef.current === 'explore')
+            setMessage(null);
         exploreCursorRef.current = cursor;
         setExploreCursor(cursor);
         const previousExploreStations = stationContextsRef.current.explore.stations;
@@ -513,7 +658,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             error: undefined
         });
         try {
-            const stations = await providers.nearby(exploreCursorLocation(cursor), 90);
+            const stations = await providers.nearby(exploreCursorLocation(cursor), 90, { signal });
             if (requestId !== exploreRequestRef.current) {
                 return;
             }
@@ -526,7 +671,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             if (screenRef.current === 'explore') {
                 setSelected(0);
             }
-            if (stations.length === 0) {
+            if (stations.length === 0 && screenRef.current === 'explore') {
                 setMessage(`No geotagged stations found near ${formatExploreCursor(cursor)}.`);
             }
         }
@@ -540,23 +685,25 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 subtitle: `World station directory unavailable near ${formatExploreCursor(cursor)}`,
                 error: loadError
             });
-            setMessage(loadError);
+            if (screenRef.current === 'explore')
+                setMessage(loadError);
         }
         finally {
             if (requestId === exploreRequestRef.current) {
-                setLoadingStations(false);
+                setStationLoading('explore', false);
             }
         }
-    }, [go, providers, setStationContextFor]);
+    }, [beginDiscovery, providers, setStationContextFor, setStationLoading]);
     const loadExplore = useCallback(async () => {
-        await loadExploreAt(exploreCursorRef.current, { resetSelection: true });
+        await loadExploreAt(exploreCursorRef.current);
     }, [loadExploreAt]);
     const moveExploreMapCursor = useCallback((direction, fast = false) => {
         const next = shiftExploreCursor(exploreCursorRef.current, direction, fast);
+        exploreRequestRef.current += 1;
         exploreCursorRef.current = next;
         setExploreCursor(next);
         setSelected(0);
-        setLoadingStations(true);
+        setStationLoading('explore', true);
         setStationContextFor('explore', {
             title: 'Explore world',
             subtitle: `Move cursor: ${formatExploreCursor(next)}`,
@@ -566,9 +713,10 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             clearTimeout(exploreMoveTimerRef.current);
         }
         exploreMoveTimerRef.current = setTimeout(() => {
-            void loadExploreAt(next, { resetSelection: true, clearMessage: false });
+            exploreMoveTimerRef.current = null;
+            void loadExploreAt(next);
         }, 220);
-    }, [loadExploreAt, setStationContextFor]);
+    }, [loadExploreAt, setStationContextFor, setStationLoading]);
     const moveExploreMapCursorToCell = useCallback((x, y) => {
         const next = exploreCursorForMouseCell(x, y, frameWidth, layout);
         if (!next) {
@@ -576,84 +724,112 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
         if (exploreMoveTimerRef.current) {
             clearTimeout(exploreMoveTimerRef.current);
+            exploreMoveTimerRef.current = null;
         }
-        void loadExploreAt(next, { resetSelection: true, clearMessage: false });
+        void loadExploreAt(next);
     }, [frameWidth, layout, loadExploreAt]);
-    const loadCountry = useCallback(async (country) => {
+    const loadCountry = useCallback(async (country, navigate = true) => {
+        const previous = stationContextsRef.current.stations;
+        if (previous.country?.code === country.code && loadingStationContextsRef.current.stations && !countryPageRequestRef.current) {
+            if (navigate)
+                go('stations');
+            return;
+        }
+        const signal = beginDiscovery('stations');
         const requestId = countryRequestRef.current + 1;
         countryRequestRef.current = requestId;
-        setLoadingStations(true);
-        setMessage(null);
+        setStationLoading('stations', true);
         countryPageRequestRef.current = null;
+        const retainedStations = previous.country?.code === country.code ? previous.stations : [];
+        setStationContextFor('stations', {
+            title: country.name,
+            subtitle: formatCountryStationsSubtitle(country, retainedStations.length, false),
+            stations: retainedStations,
+            country
+        });
+        if (navigate)
+            go('stations', { resetSelection: true });
         try {
-            const stations = await providers.byCountry(country.code, COUNTRY_STATIONS_PAGE_SIZE, 0);
+            const page = typeof providers.byCountryPage === 'function'
+                ? await providers.byCountryPage(country.code, { limit: COUNTRY_STATIONS_PAGE_SIZE, signal })
+                : legacyDiscoveryPage(await providers.byCountry(country.code, COUNTRY_STATIONS_PAGE_SIZE, 0), COUNTRY_STATIONS_PAGE_SIZE);
+            const stations = page.items;
             if (requestId !== countryRequestRef.current)
                 return;
-            showStationContext({
+            setStationContextFor('stations', {
                 title: country.name,
-                subtitle: formatCountryStationsSubtitle(country, stations.length, stations.length < country.stationCount),
+                subtitle: formatCountryStationsSubtitle(country, stations.length, !page.exhausted),
                 stations,
                 country,
-                hasMore: stations.length >= COUNTRY_STATIONS_PAGE_SIZE && stations.length < country.stationCount
-            }, 'stations');
+                hasMore: !page.exhausted, nextCursor: page.nextCursor, sources: page.sources,
+                error: discoverySourceWarning(page.sources)
+            });
+            selectedByScreenRef.current.stations = 0;
+            if (screenRef.current === 'stations')
+                setSelected(0);
         }
         catch (error) {
             if (requestId !== countryRequestRef.current)
                 return;
-            setMessage(error instanceof Error ? error.message : `Could not load ${country.name}.`);
+            const loadError = error instanceof Error ? error.message : `Could not load ${country.name}.`;
+            setStationContextFor('stations', { ...stationContextsRef.current.stations, error: loadError });
+            if (screenRef.current === 'stations')
+                setMessage(loadError);
         }
         finally {
             if (requestId === countryRequestRef.current)
-                setLoadingStations(false);
+                setStationLoading('stations', false);
         }
-    }, [providers, showStationContext]);
+    }, [beginDiscovery, go, providers, setStationContextFor, setStationLoading]);
     const loadMoreCountryStations = useCallback(async () => {
         const context = stationContextsRef.current.stations;
         const country = context.country;
-        if (!country || !context.hasMore || loadingStationsRef.current) {
+        if (!country || !context.hasMore || loadingStationContextsRef.current.stations) {
             return;
         }
         const offset = context.stations.length;
-        const requestKey = `${country.code}:${offset}`;
+        const requestId = countryRequestRef.current;
+        const requestKey = `${requestId}:${country.code}:${context.nextCursor ?? offset}`;
         if (countryPageRequestRef.current === requestKey) {
             return;
         }
         countryPageRequestRef.current = requestKey;
-        setLoadingStations(true);
+        setStationLoading('stations', true);
         try {
-            const page = await providers.byCountry(country.code, COUNTRY_STATIONS_PAGE_SIZE, offset);
+            const page = typeof providers.byCountryPage === 'function'
+                ? await providers.byCountryPage(country.code, { limit: COUNTRY_STATIONS_PAGE_SIZE, cursor: context.nextCursor, signal: discoveryAbortRef.current.stations?.signal })
+                : legacyDiscoveryPage(await providers.byCountry(country.code, COUNTRY_STATIONS_PAGE_SIZE, offset), COUNTRY_STATIONS_PAGE_SIZE);
             const latest = stationContextsRef.current.stations;
-            if (latest.country?.code !== country.code || latest.stations.length !== offset) {
+            if (requestId !== countryRequestRef.current || latest.country?.code !== country.code || latest.stations.length !== offset) {
                 return;
             }
-            const stations = appendUniqueStations(latest.stations, page);
-            const hasMore = page.length >= COUNTRY_STATIONS_PAGE_SIZE &&
-                stations.length > latest.stations.length &&
-                stations.length < country.stationCount;
+            const stations = appendUniqueStations(latest.stations, page.items);
+            const hasMore = !page.exhausted;
             setStationContextFor('stations', {
                 ...latest,
                 subtitle: formatCountryStationsSubtitle(country, stations.length, hasMore),
                 stations,
-                hasMore
+                hasMore, nextCursor: page.nextCursor, sources: page.sources,
+                error: discoverySourceWarning(page.sources)
             });
         }
         catch (error) {
-            if (stationContextsRef.current.stations.country?.code === country.code) {
+            if (requestId === countryRequestRef.current && screenRef.current === 'stations' && stationContextsRef.current.stations.country?.code === country.code) {
                 setMessage(error instanceof Error ? error.message : `Could not load more ${country.name} stations.`);
             }
         }
         finally {
             if (countryPageRequestRef.current === requestKey) {
                 countryPageRequestRef.current = null;
-                setLoadingStations(false);
+                setStationLoading('stations', false);
             }
         }
-    }, [providers, setStationContextFor]);
+    }, [providers, setStationContextFor, setStationLoading]);
     useEffect(() => {
         if (screen === 'stations' &&
             stationContexts.stations.country &&
             stationContexts.stations.hasMore &&
-            stationContexts.stations.stations.length - selected <= COUNTRY_STATIONS_LOAD_AHEAD) {
+            stationCounts.stations - selected <= COUNTRY_STATIONS_LOAD_AHEAD) {
             void loadMoreCountryStations();
         }
     }, [
@@ -662,101 +838,128 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         selected,
         stationContexts.stations.country,
         stationContexts.stations.hasMore,
-        stationContexts.stations.stations.length
+        stationCounts.stations,
+        stationContexts.stations.nextCursor
     ]);
     const runSearch = useCallback(async (query = searchQuery) => {
         if (!query.trim()) {
             setMessage('Enter a station, genre, language, or place.');
             return;
         }
+        const signal = beginDiscovery('search');
         const requestId = searchRequestRef.current + 1;
         searchRequestRef.current = requestId;
-        setLoadingStations(true);
-        setMessage(null);
+        activeSearchRef.current = { query: query.trim(), fingerprint: searchFingerprint };
+        searchPageRequestRef.current = null;
+        setStationLoading('search', true);
+        if (screenRef.current === 'search')
+            setMessage(null);
         try {
-            const stations = await providers.search(query, settingsRef.current, {
+            const pageOptions = {
                 limit: SEARCH_RESULTS_PAGE_SIZE,
-                offset: 0,
+                signal,
                 codec: filters.codec ?? undefined,
                 language: filters.language ?? undefined,
                 minBitrate: filters.minBitrate ?? undefined
-            });
+            };
+            const page = typeof providers.searchPage === 'function'
+                ? await providers.searchPage(query, settingsRef.current, pageOptions)
+                : legacyDiscoveryPage(await providers.search(query, settingsRef.current, pageOptions), SEARCH_RESULTS_PAGE_SIZE);
+            const stations = page.items;
             if (requestId !== searchRequestRef.current)
                 return;
+            searchContextFingerprintRef.current = searchFingerprint;
             setStationContextFor('search', {
                 title: `Search: ${query}`,
-                subtitle: formatSearchSubtitle(stations.length, stations.length >= SEARCH_RESULTS_PAGE_SIZE),
+                subtitle: formatSearchSubtitle(stations.length, !page.exhausted),
                 stations,
                 query: query.trim(),
-                hasMore: stations.length >= SEARCH_RESULTS_PAGE_SIZE
+                hasMore: !page.exhausted, nextCursor: page.nextCursor, sources: page.sources,
+                error: discoverySourceWarning(page.sources)
             });
             selectedByScreenRef.current.search = 0;
             lastSubmittedSearchRef.current = query.trim();
-            setLibrary(store.addSearch(query));
+            persistLibrary(() => store.addSearch(query));
             searchHistoryRef.current = { cursor: -1, draft: '' };
-            setSelected(0);
-            setEditingSearch(true);
+            if (screenRef.current === 'search') {
+                setSelected(0);
+                setEditingSearch(true);
+            }
         }
         catch (error) {
             if (requestId !== searchRequestRef.current)
                 return;
-            setMessage(error instanceof Error ? error.message : 'Search failed.');
+            if (screenRef.current === 'search')
+                setMessage(error instanceof Error ? error.message : 'Search failed.');
         }
         finally {
             if (requestId === searchRequestRef.current)
-                setLoadingStations(false);
+                setStationLoading('search', false);
         }
-    }, [filters, providers, searchQuery, setStationContextFor, store]);
+    }, [beginDiscovery, filters, persistLibrary, providers, searchFingerprint, searchQuery, setStationContextFor, setStationLoading, store]);
+    useEffect(() => {
+        const active = activeSearchRef.current;
+        // A cursor belongs to the exact server filters and enabled directories.
+        // Reissue the submitted query, including when a previous request is pending.
+        if (active && active.fingerprint !== searchFingerprint)
+            void runSearch(active.query);
+    }, [runSearch, searchFingerprint]);
     const loadMoreSearchResults = useCallback(async () => {
         const context = stationContextsRef.current.search;
         const query = context.query;
-        if (!query || !context.hasMore || loadingStationsRef.current) {
+        if (!query || !context.hasMore || loadingStationContextsRef.current.search || searchContextFingerprintRef.current !== searchFingerprint) {
             return;
         }
         const offset = context.stations.length;
-        const requestKey = `${query}:${offset}:${filters.codec ?? ''}:${filters.language ?? ''}:${filters.minBitrate ?? ''}`;
+        const requestId = searchRequestRef.current;
+        const requestKey = `${requestId}:${query}:${context.nextCursor ?? offset}:${filters.codec ?? ''}:${filters.language ?? ''}:${filters.minBitrate ?? ''}`;
         if (searchPageRequestRef.current === requestKey) {
             return;
         }
         searchPageRequestRef.current = requestKey;
-        setLoadingStations(true);
+        setStationLoading('search', true);
         try {
-            const page = await providers.search(query, settingsRef.current, {
+            const pageOptions = {
                 limit: SEARCH_RESULTS_PAGE_SIZE,
-                offset,
+                cursor: context.nextCursor,
+                signal: discoveryAbortRef.current.search?.signal,
                 codec: filters.codec ?? undefined,
                 language: filters.language ?? undefined,
                 minBitrate: filters.minBitrate ?? undefined
-            });
+            };
+            const page = typeof providers.searchPage === 'function'
+                ? await providers.searchPage(query, settingsRef.current, pageOptions)
+                : legacyDiscoveryPage(await providers.search(query, settingsRef.current, { ...pageOptions, offset }), SEARCH_RESULTS_PAGE_SIZE);
             const latest = stationContextsRef.current.search;
-            if (latest.query !== query || latest.stations.length !== offset) {
+            if (requestId !== searchRequestRef.current || latest.query !== query || latest.stations.length !== offset) {
                 return;
             }
-            const stations = appendUniqueStations(latest.stations, page);
-            const hasMore = page.length >= SEARCH_RESULTS_PAGE_SIZE && stations.length > latest.stations.length;
+            const stations = appendUniqueStations(latest.stations, page.items);
+            const hasMore = !page.exhausted;
             setStationContextFor('search', {
                 ...latest,
                 subtitle: formatSearchSubtitle(stations.length, hasMore),
                 stations,
-                hasMore
+                hasMore, nextCursor: page.nextCursor, sources: page.sources,
+                error: discoverySourceWarning(page.sources)
             });
         }
         catch (error) {
-            if (stationContextsRef.current.search.query === query) {
+            if (requestId === searchRequestRef.current && screenRef.current === 'search' && stationContextsRef.current.search.query === query) {
                 setMessage(error instanceof Error ? error.message : 'Could not load more search results.');
             }
         }
         finally {
             if (searchPageRequestRef.current === requestKey) {
                 searchPageRequestRef.current = null;
-                setLoadingStations(false);
+                setStationLoading('search', false);
             }
         }
-    }, [filters, providers, setStationContextFor]);
+    }, [filters, providers, searchFingerprint, setStationContextFor, setStationLoading]);
     useEffect(() => {
         if (screen === 'search' &&
             stationContexts.search.hasMore &&
-            stationContexts.search.stations.length - selected <= SEARCH_RESULTS_LOAD_AHEAD) {
+            stationCounts.search - selected <= SEARCH_RESULTS_LOAD_AHEAD) {
             void loadMoreSearchResults();
         }
     }, [
@@ -764,7 +967,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         screen,
         selected,
         stationContexts.search.hasMore,
-        stationContexts.search.stations.length
+        stationCounts.search,
+        stationContexts.search.nextCursor
     ]);
     const recallSearchHistory = useCallback((direction) => {
         const history = store.snapshot().searchHistory;
@@ -789,19 +993,21 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
     }, [searchQuery, store]);
     const loadNearby = useCallback(async () => {
+        const signal = beginDiscovery('nearby');
         const requestId = nearbyRequestRef.current + 1;
         nearbyRequestRef.current = requestId;
-        setLoadingStations(true);
-        setMessage(null);
+        setStationLoading('nearby', true);
+        if (screenRef.current === 'nearby')
+            setMessage(null);
         setStationContextFor('nearby', {
             ...stationContextsRef.current.nearby,
             error: undefined
         });
-        go('nearby', { resetSelection: stationContextsRef.current.nearby.stations.length === 0 });
         try {
             if (!settingsRef.current.enableNearbyLocation) {
                 if (stationContextsRef.current.nearby.stations.length > 0) {
-                    setMessage('Nearby location lookup is off. Showing the last nearby station list.');
+                    if (screenRef.current === 'nearby')
+                        setMessage('Nearby location lookup is off. Showing the last nearby station list.');
                     return;
                 }
                 setStationContextFor('nearby', {
@@ -812,13 +1018,14 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 });
                 return;
             }
-            const detected = location ?? (await providers.detectLocation());
+            const detected = location ?? (await providers.detectLocation({ signal }));
             if (requestId !== nearbyRequestRef.current)
                 return;
             setLocation(detected);
             if (!detected) {
                 if (stationContextsRef.current.nearby.stations.length > 0) {
-                    setMessage('Location detection is unavailable. Showing the last nearby station list.');
+                    if (screenRef.current === 'nearby')
+                        setMessage('Location detection is unavailable. Showing the last nearby station list.');
                     return;
                 }
                 setStationContextFor('nearby', {
@@ -829,7 +1036,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 });
                 return;
             }
-            const stations = await providers.nearby(detected, 90);
+            const stations = await providers.nearby(detected, 90, { signal });
             if (requestId !== nearbyRequestRef.current)
                 return;
             setStationContextFor('nearby', {
@@ -846,17 +1053,20 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 ...stationContextsRef.current.nearby,
                 error: loadError
             });
-            setMessage(loadError);
+            if (screenRef.current === 'nearby')
+                setMessage(loadError);
         }
         finally {
             if (requestId === nearbyRequestRef.current)
-                setLoadingStations(false);
+                setStationLoading('nearby', false);
         }
-    }, [go, location, providers, setStationContextFor]);
+    }, [beginDiscovery, location, providers, setStationContextFor, setStationLoading]);
     const queueFromCurrentList = useCallback((station) => {
         const sourceScreen = screenRef.current;
         const sourceContextKey = stationContextKeyForScreen(sourceScreen);
-        const currentList = displayStationsRef.current;
+        const currentList = sourceContextKey
+            ? applyStationFilters(stationContextsRef.current[sourceContextKey].stations, filters)
+            : displayStationsRef.current;
         if (currentList.some(item => stationMatches(item, station))) {
             return {
                 title: sourceContextKey ? stationContextsRef.current[sourceContextKey].title : 'Current station list',
@@ -874,7 +1084,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             sourceContextKey: null,
             stations: [station]
         };
-    }, [queueContainsStation, stationMatches]);
+    }, [filters, queueContainsStation, stationMatches]);
     const rememberQueueSelection = useCallback((queue, index) => {
         if (queue.sourceContextKey) {
             selectedByScreenRef.current[queue.sourceScreen] = index;
@@ -885,68 +1095,45 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
     }, []);
     const playStation = useCallback(async (station, options = {}) => {
-        const requestId = tuneRequestRef.current + 1;
-        tuneRequestRef.current = requestId;
-        if (skipBrokenTimerRef.current) {
-            clearTimeout(skipBrokenTimerRef.current);
-            skipBrokenTimerRef.current = null;
-        }
+        if (options.signal?.aborted)
+            return;
+        if (!options.outputChange)
+            outputCancellationRef.current += 1;
+        const requestId = ++tuneRequestRef.current;
+        const pendingSettings = settingsQueueRef.current;
         const queue = options.queue ?? queueFromCurrentList(station);
-        setTuningStation(station);
-        setNowPlaying(null);
         try {
-            // Cancel any in-flight backend startup before resolving the next tune.
-            // This prevents a slower, older request from becoming audible after a
-            // newer station was selected.
-            await player.stop();
-            if (requestId !== tuneRequestRef.current)
-                return;
-            const resolved = await providers.resolve(station);
-            if (requestId !== tuneRequestRef.current)
+            await pendingSettings;
+            if (requestId !== tuneRequestRef.current || options.signal?.aborted)
                 return;
-            await player.play(station, resolved.url);
+            desktopSuspendedRef.current = false;
+            playbackQueueRef.current = queue;
+            const tuned = await engine.tune(station, { queue: queue.stations, startPaused: options.startPaused, signal: options.signal });
             if (requestId !== tuneRequestRef.current)
                 return;
-            playingStationRef.current = station;
-            setPlayingStation(station);
-            setTuningStation(null);
-            playbackQueueRef.current = queue;
-            const nextLibrary = store.addRecent(station);
+            const index = queue.stations.findIndex(item => stationMatches(item, tuned));
+            if (index >= 0 && !stationMatches(tuned, station))
+                rememberQueueSelection(queue, index);
+            desktopMediaRef.current?.refresh();
             if (screenRef.current === 'library') {
-                const nextLibraryStations = applyStationFilters(buildLibraryStations(nextLibrary), filters);
-                const nextLibraryIndex = nextLibraryStations.findIndex(item => stationMatches(item, station));
-                if (nextLibraryIndex >= 0) {
-                    selectedByScreenRef.current.library = nextLibraryIndex;
-                    setSelected(nextLibraryIndex);
+                const nextLibraryStations = applyStationFilters(buildLibraryStations(store.getSnapshot()), filters);
+                const nextIndex = nextLibraryStations.findIndex(item => stationMatches(item, tuned));
+                if (nextIndex >= 0) {
+                    selectedByScreenRef.current.library = nextIndex;
+                    setSelected(nextIndex);
                 }
             }
-            setLibrary(nextLibrary);
-            if (options.openNowPlaying) {
+            if (options.openNowPlaying)
                 go('now-playing');
-            }
             setMessage(null);
+            return tuned;
         }
         catch (error) {
-            if (requestId !== tuneRequestRef.current)
-                return;
-            const message = error instanceof Error ? error.message : 'Could not tune station.';
-            const currentList = queue.stations;
-            const currentIndex = currentList.findIndex(item => stationKey(item) === stationKey(station));
-            const nextStation = currentIndex >= 0 ? currentList[currentIndex + 1] : undefined;
-            if (shouldSkipAfterTuneError(error, settingsRef.current.skipBrokenStreams, nextStation)) {
-                setMessage(`${message} Skipping to ${nextStation.name}.`);
-                setTuningStation(nextStation);
-                rememberQueueSelection(queue, currentIndex + 1);
-                skipBrokenTimerRef.current = setTimeout(() => {
-                    skipBrokenTimerRef.current = null;
-                    playStationRef.current(nextStation, { ...options, queue });
-                }, BROKEN_STREAM_AUTO_SKIP_DELAY_MS);
+            if (requestId !== tuneRequestRef.current || options.signal?.aborted || error.name === 'AbortError')
                 return;
-            }
-            setTuningStation(null);
-            setMessage(message);
+            setMessage(error instanceof Error ? error.message : 'Could not tune station.');
         }
-    }, [filters, go, player, providers, queueFromCurrentList, rememberQueueSelection, stationMatches, store]);
+    }, [engine, filters, go, queueFromCurrentList, rememberQueueSelection, stationMatches, store]);
     // Resume the most recent station on launch when opted in, like a radio
     // powering back on to its last frequency. Runs once and never auto-navigates.
     const didResumeRef = useRef(false);
@@ -955,6 +1142,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             return;
         }
         didResumeRef.current = true;
+        if (playbackSession?.status.station || playbackSession?.status.tui?.tuningStation)
+            return;
         if (!settingsRef.current.resumeOnLaunch) {
             return;
         }
@@ -962,17 +1151,14 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         if (last) {
             void playStation(last);
         }
-    }, [playStation, store]);
-    playStationRef.current = playStation;
+    }, [playStation, store, playbackSession]);
     const cancelPendingAutoSkip = useCallback(() => {
-        if (!skipBrokenTimerRef.current)
+        if (!engine.snapshot().message?.includes('Skipping to'))
             return;
-        clearTimeout(skipBrokenTimerRef.current);
-        skipBrokenTimerRef.current = null;
-        setTuningStation(null);
+        cancelPendingTune();
         setMessage('Auto-skip canceled. Choose a station and press Enter.');
-    }, []);
-    const showTransientFooterMessage = useCallback((nextMessage, durationMs = VISUALIZER_MESSAGE_MS) => {
+    }, [cancelPendingTune, engine]);
+    const showTransientFooterMessage = useCallback((nextMessage, durationMs = TRANSIENT_NOTICE_MS) => {
         if (transientFooterMessageTimerRef.current) {
             clearTimeout(transientFooterMessageTimerRef.current);
         }
@@ -992,37 +1178,48 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         showTransientFooterMessage('Ctrl+C again to exit', EXIT_CONFIRMATION_MS);
     }, [showTransientFooterMessage, shutdown]);
     const toggleFavorite = useCallback((station) => {
-        if (!station) {
-            setMessage('Select or play a station before pressing f.');
-            return;
-        }
-        const wasFavorite = store.isFavorite(station);
-        setLibrary(store.toggleFavorite(station));
-        const favoriteMessage = `${wasFavorite ? 'Removed from' : 'Added to'} favorites: ${station.name}`;
-        if (screenRef.current === 'library') {
-            showTransientFooterMessage(favoriteMessage);
-        }
-        else {
-            setMessage(favoriteMessage);
-        }
-        if (!wasFavorite && settingsRef.current.shareDirectoryVotes) {
-            // Best-effort upvote back to the directory; never blocks favoriting.
-            void providers.vote(station);
-        }
-    }, [providers, showTransientFooterMessage, store]);
+        const operation = (async () => {
+            if (!station) {
+                setMessage('Select or play a station before pressing f.');
+                return;
+            }
+            const wasFavorite = store.isFavorite(station);
+            setLibrary(localSessionLibrary(await store.toggleFavorite(station), platform, player.airPlaySelectionRequired()));
+            setPersistenceWarning(null);
+            engine.clearWarning();
+            const favoriteMessage = `${wasFavorite ? 'Removed from' : 'Added to'} favorites: ${station.name}`;
+            if (screenRef.current === 'library' || screenRef.current === 'search') {
+                showTransientFooterMessage(favoriteMessage);
+            }
+            else {
+                showTransientMessage(favoriteMessage);
+            }
+            if (!wasFavorite && settingsRef.current.shareDirectoryVotes) {
+                // Best-effort upvote back to the directory; never blocks favoriting.
+                void providers.vote(station).catch(reportActionError);
+            }
+        })();
+        void operation.catch(reportActionError);
+        return operation;
+    }, [engine, platform, player, providers, reportActionError, showTransientFooterMessage, showTransientMessage, store]);
     const showControlResult = useCallback((result) => {
         if (!result.ok && result.message) {
             setMessage(result.message);
         }
     }, []);
-    const openStationHomepage = useCallback((station) => {
+    const openStationHomepage = useCallback(async (station) => {
         if (!station?.homepage) {
             setMessage('This station has no homepage.');
             return;
         }
-        setMessage(openExternal(station.homepage)
+        const url = safeExternalHttpUrl(station.homepage);
+        if (!url) {
+            setMessage('This station has no valid HTTP(S) homepage.');
+            return;
+        }
+        setMessage(await openExternal(url)
             ? `Opening homepage: ${station.name}`
-            : 'That station homepage is not a valid HTTP(S) URL.');
+            : `Could not open a browser in this session. Homepage: ${sanitizeTerminalText(url) ?? ''}`);
     }, []);
     const copyStationUrl = useCallback(async (station) => {
         if (!station) {
@@ -1033,23 +1230,29 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         if (!url) {
             url = await providers.resolve(station).then(resolved => resolved.url).catch(() => undefined);
         }
-        if (!url) {
-            setMessage(`No stream URL available for ${station.name}.`);
+        const safeUrl = url ? safeMediaTarget(url) : null;
+        if (!safeUrl) {
+            setMessage(`No safe stream URL available for ${station.name}.`);
             return;
         }
-        const copied = copyToClipboard(url);
-        setMessage(copied ? `Copied stream URL: ${station.name}` : `Stream URL: ${url}`);
+        const copied = await copyToClipboard(safeUrl);
+        setMessage(copied ? `Copied stream URL: ${station.name}` : `Stream URL: ${sanitizeTerminalText(safeUrl) ?? ''}`);
     }, [providers]);
-    const submitAirPlayCode = useCallback((code) => {
-        const result = player.submitAirPlayPasscode(code);
-        if (result.ok) {
-            setAirPlayCode('');
-            setMessage(result.message ?? 'AirPlay code sent.');
-            go('now-playing', { clearMessage: false });
-            return;
+    const submitAirPlayCode = useCallback(async (code) => {
+        try {
+            const result = await player.submitAirPlayPasscode(code);
+            if (result.ok) {
+                setAirPlayCode('');
+                setMessage(result.message ?? 'AirPlay code sent.');
+                go('now-playing', { clearMessage: false });
+                return;
+            }
+            showControlResult(result);
         }
-        showControlResult(result);
-    }, [go, player, showControlResult]);
+        catch (error) {
+            reportActionError(error);
+        }
+    }, [go, player, showControlResult, reportActionError]);
     const setVolume = useCallback((volume) => {
         const clamped = clampVolume(volume);
         const requestId = volumeRequestRef.current + 1;
@@ -1059,8 +1262,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 updateSettings({ volume: player.getState().volume });
             }
             showControlResult(result);
-        });
-    }, [player, showControlResult, updateSettings]);
+        }).catch(reportActionError);
+    }, [player, reportActionError, showControlResult, updateSettings]);
     const adjustVolume = useCallback((delta) => {
         const requestId = volumeRequestRef.current + 1;
         volumeRequestRef.current = requestId;
@@ -1069,62 +1272,66 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 updateSettings({ volume: player.getState().volume });
             }
             showControlResult(result);
-        });
-    }, [player, showControlResult, updateSettings]);
+        }).catch(reportActionError);
+    }, [player, reportActionError, showControlResult, updateSettings]);
     const toggleMute = useCallback(() => {
-        void player.toggleMute().then(showControlResult);
-    }, [player, showControlResult]);
+        void player.toggleMute().then(showControlResult).catch(reportActionError);
+    }, [player, reportActionError, showControlResult]);
     const togglePause = useCallback(() => {
-        void player.togglePause().then(showControlResult);
-    }, [player, showControlResult]);
-    const showTransientMessage = useCallback((nextMessage) => {
-        if (transientMessageTimerRef.current) {
-            clearTimeout(transientMessageTimerRef.current);
-        }
-        setMessage(nextMessage);
-        transientMessageTimerRef.current = setTimeout(() => {
-            setMessage(currentMessage => currentMessage === nextMessage ? null : currentMessage);
-            transientMessageTimerRef.current = null;
-        }, VISUALIZER_MESSAGE_MS);
-    }, []);
+        void player.togglePause().then(showControlResult).catch(reportActionError);
+    }, [player, reportActionError, showControlResult]);
     const cycleDisplayColor = useCallback(() => {
-        const theme = nextTheme(settingsRef.current.theme);
-        updateSettings({ theme });
-        showTransientMessage(`Display color: ${theme}`);
+        void updateSettings(current => ({ theme: nextTheme(current.theme) }))
+            .then(saved => showTransientMessage(`Display color: ${saved.settings.theme}`)).catch(() => undefined);
     }, [showTransientMessage, updateSettings]);
     const cycleReceiverStyle = useCallback(() => {
-        const receiverStyle = nextReceiverStyle(settingsRef.current.receiverStyle);
-        updateSettings({ receiverStyle });
-        showTransientMessage(`Receiver style: ${receiverStyle}`);
+        void updateSettings(current => ({ receiverStyle: nextReceiverStyle(current.receiverStyle) }))
+            .then(saved => showTransientMessage(`Receiver style: ${saved.settings.receiverStyle}`)).catch(() => undefined);
     }, [showTransientMessage, updateSettings]);
     const toggleRadioGarden = useCallback(() => {
-        const enableRadioGarden = !settingsRef.current.enableRadioGarden;
-        updateSettings({ enableRadioGarden });
-        setMessage(`Radio Garden ${enableRadioGarden ? 'enabled' : 'disabled'}.`);
-        setTimeout(refreshProviderHealth, 0);
-    }, [refreshProviderHealth, updateSettings]);
+        void (async () => {
+            const { settings: { enableRadioGarden } } = await updateSettings(current => ({ enableRadioGarden: !current.enableRadioGarden }));
+            setMessage(`Radio Garden ${enableRadioGarden ? 'enabled' : 'disabled'}.`);
+            setTimeout(refreshProviderHealth, 0);
+        })().catch(reportActionError);
+    }, [refreshProviderHealth, reportActionError, updateSettings]);
     const toggleNearbyLocation = useCallback(() => {
-        const enableNearbyLocation = !settingsRef.current.enableNearbyLocation;
-        updateSettings({ enableNearbyLocation });
-        setMessage(`Nearby location lookup ${enableNearbyLocation ? 'enabled' : 'disabled'}.`);
-        if (enableNearbyLocation && screenRef.current === 'nearby') {
-            setTimeout(() => void loadNearby(), 0);
-        }
-        else if (!enableNearbyLocation && screenRef.current === 'nearby') {
-            const current = stationContextsRef.current.nearby;
-            setStationContextFor('nearby', {
-                ...current,
-                subtitle: 'Location lookup off · showing the last loaded results',
-                error: undefined
-            });
-        }
-    }, [loadNearby, setStationContextFor, updateSettings]);
+        void (async () => {
+            const { settings: { enableNearbyLocation } } = await updateSettings(current => ({ enableNearbyLocation: !current.enableNearbyLocation }));
+            setMessage(`Nearby location lookup ${enableNearbyLocation ? 'enabled' : 'disabled'}.`);
+            if (enableNearbyLocation && screenRef.current === 'nearby') {
+                setTimeout(() => void loadNearby(), 0);
+            }
+            else if (!enableNearbyLocation && screenRef.current === 'nearby') {
+                const current = stationContextsRef.current.nearby;
+                setStationContextFor('nearby', {
+                    ...current,
+                    subtitle: 'Location lookup off · showing the last loaded results',
+                    error: undefined
+                });
+            }
+        })().catch(reportActionError);
+    }, [loadNearby, reportActionError, setStationContextFor, updateSettings]);
     const toggleDirectoryVoting = useCallback(() => {
-        const shareDirectoryVotes = !settingsRef.current.shareDirectoryVotes;
-        updateSettings({ shareDirectoryVotes });
-        setMessage(`Radio Browser favorite votes ${shareDirectoryVotes ? 'enabled' : 'disabled'}.`);
-    }, [updateSettings]);
+        void (async () => {
+            const { settings: { shareDirectoryVotes } } = await updateSettings(current => ({ shareDirectoryVotes: !current.shareDirectoryVotes }));
+            setMessage(`Radio Browser favorite votes ${shareDirectoryVotes ? 'enabled' : 'disabled'}.`);
+        })().catch(reportActionError);
+    }, [reportActionError, updateSettings]);
     const refreshAirPlayTargets = useCallback(async (announce = true) => {
+        if (!airPlaySupported) {
+            if (announce)
+                showTransientMessage(airPlayUnavailableMessage);
+            return [];
+        }
+        if (platform === 'linux' && !player.refreshDetectedBackends().includes('airplay')) {
+            setMessage(airPlaySetupRequiredMessage);
+            throw new PlaybackOutputError(airPlaySetupRequiredMessage);
+        }
+        if (networkPolicy().offline) {
+            setMessage('AirPlay discovery is disabled by RADIOCLI_OFFLINE=1.');
+            return [];
+        }
         try {
             const devices = await player.refreshAirPlayDevices();
             setAvailableAirPlayDevices(devices);
@@ -1140,98 +1347,113 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             }
             return devices;
         }
-        catch {
+        catch (error) {
             setAvailableAirPlayDevices([]);
-            if (announce) {
-                setMessage('AirPlay receiver refresh failed.');
-            }
-            return [];
+            throw error instanceof Error ? error : new Error('AirPlay receiver refresh failed.');
         }
-    }, [player]);
+    }, [airPlaySupported, airPlayUnavailableMessage, platform, player, showTransientMessage]);
     const openAirPlaySettings = useCallback(() => {
+        if (!airPlaySupported) {
+            showTransientMessage(airPlayUnavailableMessage);
+            return;
+        }
         const preferredIndex = availableAirPlayDevices.findIndex(device => device.id === settingsRef.current.preferredAirPlayDevice);
         selectedByScreenRef.current['airplay-settings'] = Math.max(0, preferredIndex);
         go('airplay-settings', { resetSelection: false });
-        void refreshAirPlayTargets(false);
-    }, [availableAirPlayDevices, go, refreshAirPlayTargets]);
+        void refreshAirPlayTargets(false).catch(reportActionError);
+    }, [airPlaySupported, airPlayUnavailableMessage, availableAirPlayDevices, go, refreshAirPlayTargets, reportActionError, showTransientMessage]);
     const selectAirPlayDeviceAt = useCallback((index) => {
-        const device = availableAirPlayDevices[index];
-        if (!device) {
-            setMessage('No AirPlay receiver selected.');
-            return;
-        }
-        updateSettings({ preferredAirPlayDevice: device.id });
-        selectedByScreenRef.current['airplay-settings'] = index;
-        if (device.local) {
-            const preferredBackend = preferredLocalPlaybackBackend(availableBackends);
+        pendingOutputChangesRef.current += 1;
+        void (async () => {
+            const requestId = outputCancellationRef.current;
+            const device = availableAirPlayDevices[index];
+            if (!device) {
+                setMessage('No AirPlay receiver selected.');
+                return;
+            }
+            const preferredBackend = device.local
+                ? preferredLocalPlaybackBackend(availableBackends)
+                : isAirPlayBackendAvailable(availableBackends) ? 'airplay' : null;
+            await updateSettings({ preferredAirPlayDevice: device.id, ...(preferredBackend ? { preferredBackend } : {}) });
+            if (requestId !== outputCancellationRef.current)
+                return;
+            selectedByScreenRef.current['airplay-settings'] = index;
+            if (device.local) {
+                if (!preferredBackend) {
+                    setMessage(`${device.name} is ${airPlayLocalDeviceLabel(platform)}. Install mpv to use local playback instead of AirPlay.`);
+                    return;
+                }
+                if (playingStation && shouldRetuneForAudioOutput(playback.state)) {
+                    const queue = playbackQueueRef.current ?? queueFromCurrentList(playingStation);
+                    setMessage(`${device.name} is ${airPlayLocalDeviceLabel(platform)}. Switching audio to ${audioOutputLabel(preferredBackend)}...`);
+                    await playStation(playingStation, { queue, outputChange: true });
+                    return;
+                }
+                setMessage(`${device.name} is ${airPlayLocalDeviceLabel(platform)}. Audio output: ${audioOutputLabel(preferredBackend)}.`);
+                return;
+            }
             if (!preferredBackend) {
-                setMessage(`${device.name} is this Mac. Install mpv to use local playback instead of AirPlay.`);
+                setMessage(`AirPlay receiver: ${device.name}. AirPlay playback is unavailable; run radiocli doctor.`);
                 return;
             }
-            updateSettings({ preferredBackend });
             if (playingStation && shouldRetuneForAudioOutput(playback.state)) {
                 const queue = playbackQueueRef.current ?? queueFromCurrentList(playingStation);
-                setMessage(`${device.name} is this Mac. Switching audio to ${audioOutputLabel(preferredBackend)}...`);
-                void playStation(playingStation, { queue });
+                setMessage(`Switching audio to AirPlay: ${device.name}...`);
+                await playStation(playingStation, { queue, outputChange: true });
                 return;
             }
-            setMessage(`${device.name} is this Mac. Audio output: ${audioOutputLabel(preferredBackend)}.`);
-            return;
-        }
-        if (!isAirPlayBackendAvailable(availableBackends)) {
-            setMessage(`AirPlay receiver: ${device.name}. AirPlay playback is unavailable; run radiocli doctor.`);
-            return;
-        }
-        updateSettings({ preferredBackend: 'airplay' });
-        if (playingStation && shouldRetuneForAudioOutput(playback.state)) {
-            const queue = playbackQueueRef.current ?? queueFromCurrentList(playingStation);
-            setMessage(`Switching audio to AirPlay: ${device.name}...`);
-            void playStation(playingStation, { queue });
-            return;
-        }
-        setMessage(`AirPlay receiver: ${device.name}. Audio output: AirPlay.`);
-    }, [availableAirPlayDevices, availableBackends, playback.state, playStation, playingStation, queueFromCurrentList, updateSettings]);
+            setMessage(`AirPlay receiver: ${device.name}. Audio output: AirPlay.`);
+        })().catch(reportActionError).finally(() => { pendingOutputChangesRef.current -= 1; });
+    }, [availableAirPlayDevices, availableBackends, platform, playback.state, player, playStation, playingStation, queueFromCurrentList, reportActionError, updateSettings]);
     const cycleAudioOutput = useCallback(() => {
-        const currentOutput = settingsRef.current.preferredBackend;
-        const activeNeedsSelectedOutput = Boolean(playingStation &&
-            shouldRetuneForAudioOutput(playback.state) &&
-            audioOutputCanApply(currentOutput, settingsRef.current) &&
-            audioOutputNeedsActiveSwitch(currentOutput, playback.backend, availableBackends));
-        const preferredBackend = activeNeedsSelectedOutput
-            ? currentOutput
-            : nextAvailablePlaybackBackend(currentOutput, availableBackends);
-        updateSettings({ preferredBackend });
-        if (preferredBackend === 'airplay' && !settingsRef.current.preferredAirPlayDevice) {
-            setMessage('Choose an AirPlay receiver first. Your current station will keep playing until you pick one.');
-            openAirPlaySettings();
-            return;
-        }
-        if (playingStation && shouldRetuneForAudioOutput(playback.state)) {
-            const queue = playbackQueueRef.current ?? queueFromCurrentList(playingStation);
-            setMessage(`Switching audio to ${audioOutputSwitchLabel(preferredBackend, availableBackends)}...`);
-            void playStation(playingStation, { queue });
-            return;
-        }
-        setMessage(`Audio output: ${audioOutputSwitchLabel(preferredBackend, availableBackends)}.`);
-    }, [availableBackends, openAirPlaySettings, playback.backend, playback.state, playStation, playingStation, queueFromCurrentList, updateSettings]);
+        const precedingOutputChange = pendingOutputChangesRef.current > 0;
+        pendingOutputChangesRef.current += 1;
+        void (async () => {
+            const requestId = outputCancellationRef.current;
+            let preferredBackend;
+            await updateSettings(current => {
+                const currentPlayback = player.getState();
+                const activeNeedsSelectedOutput = Boolean(!precedingOutputChange && playingStation &&
+                    shouldRetuneForAudioOutput(currentPlayback.state) &&
+                    audioOutputCanApply(current.preferredBackend, current) &&
+                    audioOutputNeedsActiveSwitch(current.preferredBackend, currentPlayback.backend, availableBackends));
+                preferredBackend = activeNeedsSelectedOutput
+                    ? current.preferredBackend
+                    : nextAvailablePlaybackBackend(current.preferredBackend, platform === 'linux' && airPlaySupported ? [...new Set([...availableBackends, 'airplay'])] : availableBackends);
+                return { preferredBackend };
+            });
+            if (requestId !== outputCancellationRef.current)
+                return;
+            if (preferredBackend === 'airplay' && (!settingsRef.current.preferredAirPlayDevice || player.airPlaySelectionRequired())) {
+                setMessage('Choose an AirPlay receiver first. Your current station will keep playing until you pick one.');
+                openAirPlaySettings();
+                return;
+            }
+            if (playingStation && shouldRetuneForAudioOutput(playback.state)) {
+                const queue = playbackQueueRef.current ?? queueFromCurrentList(playingStation);
+                setMessage(`Switching audio to ${audioOutputSwitchLabel(preferredBackend, availableBackends)}...`);
+                await playStation(playingStation, { queue, outputChange: true });
+                return;
+            }
+            setMessage(`Audio output: ${audioOutputSwitchLabel(preferredBackend, availableBackends)}.`);
+        })().catch(reportActionError).finally(() => { pendingOutputChangesRef.current -= 1; });
+    }, [airPlaySupported, availableBackends, openAirPlaySettings, platform, playback.state, player, playStation, playingStation, queueFromCurrentList, reportActionError, updateSettings]);
     const toggleSkipBrokenStreams = useCallback(() => {
-        const skipBrokenStreams = !settingsRef.current.skipBrokenStreams;
-        updateSettings({ skipBrokenStreams });
-        setMessage(`Skip broken streams ${skipBrokenStreams ? 'enabled' : 'disabled'}.`);
+        void updateSettings(current => ({ skipBrokenStreams: !current.skipBrokenStreams }))
+            .then(saved => setMessage(`Skip broken streams ${saved.settings.skipBrokenStreams ? 'enabled' : 'disabled'}.`))
+            .catch(() => undefined);
     }, [updateSettings]);
     const toggleSetting = useCallback((key) => {
-        const current = key === 'mouseSupport'
-            ? settingsRef.current.mouseSupport !== false
-            : Boolean(settingsRef.current[key]);
-        const next = !current;
-        updateSettings({ [key]: next });
-        setMessage(`${settingToggleLabel[key]} ${next ? 'on' : 'off'}.`);
+        void updateSettings(current => ({ [key]: key === 'mouseSupport' ? current.mouseSupport === false : !current[key] }))
+            .then(saved => setMessage(`${settingToggleLabel[key]} ${saved.settings[key] ? 'on' : 'off'}.`))
+            .catch(() => undefined);
     }, [updateSettings]);
     const toggleAgentSetting = useCallback((key) => {
-        const agentControl = settingsRef.current.agentControl ?? defaultAgentControlSettings;
-        const next = !agentControl[key];
-        updateSettings({ agentControl: { ...agentControl, [key]: next } });
-        setMessage(`Agent ${key === 'openUiOnPlay' ? 'TUI launch' : 'Now Playing focus'} ${next ? 'on' : 'off'}.`);
+        void updateSettings(current => {
+            const agentControl = current.agentControl ?? defaultAgentControlSettings;
+            return { agentControl: { ...agentControl, [key]: !agentControl[key] } };
+        }).then(saved => setMessage(`Agent ${key === 'openUiOnPlay' ? 'TUI launch' : 'Now Playing focus'} ${saved.settings.agentControl?.[key] ? 'on' : 'off'}.`))
+            .catch(() => undefined);
     }, [updateSettings]);
     const setAgentIntegrationEnabled = useCallback(async () => {
         if (configuringMcpRef.current) {
@@ -1239,19 +1461,18 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             return;
         }
         configuringMcpRef.current = true;
+        await settingsQueueRef.current;
         const enabled = !(settingsRef.current.agentControl ?? defaultAgentControlSettings).enabled;
         setMessage(enabled ? 'Setting up agent and Codex Voice control...' : 'Disabling agent and voice control...');
         try {
             const results = await mcpConfigurator(enabled, mcpRuntime(), null);
             const failed = results.filter(item => item.status === 'failed');
-            const agentControl = settingsRef.current.agentControl ?? defaultAgentControlSettings;
-            updateSettings({ agentControl: { ...agentControl, enabled } });
+            await updateSettings(current => ({ agentControl: { ...(current.agentControl ?? defaultAgentControlSettings), enabled } }));
             setMessage(integrationResultMessage(enabled, results, failed));
         }
         catch (error) {
             if (!enabled) {
-                const agentControl = settingsRef.current.agentControl ?? defaultAgentControlSettings;
-                updateSettings({ agentControl: { ...agentControl, enabled: false } });
+                await updateSettings(current => ({ agentControl: { ...(current.agentControl ?? defaultAgentControlSettings), enabled: false } }));
             }
             setMessage(`Agent integration ${enabled ? 'setup' : 'removal'} failed: ${error instanceof Error ? error.message : String(error)}`);
         }
@@ -1269,8 +1490,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         try {
             const results = await mcpConfigurator(true, mcpRuntime(), null);
             const failed = results.filter(item => item.status === 'failed');
-            const agentControl = settingsRef.current.agentControl ?? defaultAgentControlSettings;
-            updateSettings({ agentControl: { ...agentControl, enabled: true } });
+            await updateSettings(current => ({ agentControl: { ...(current.agentControl ?? defaultAgentControlSettings), enabled: true } }));
             setMessage(integrationResultMessage(true, results, failed));
         }
         catch (error) {
@@ -1284,42 +1504,44 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         const currentMinutes = sleepUntil ? Math.round((sleepUntil - Date.now()) / 60000) : null;
         const next = nextSleepTimerMinutes(currentMinutes);
         setSleepUntil(next ? Date.now() + next * 60_000 : null);
-    }, [sleepUntil]);
+    }, [sleepUntil, setSleepUntil]);
     const openLibrary = useCallback(() => {
         go('library', { resetSelection: false });
     }, [go]);
     const selectedStation = displayStations[selected] ?? null;
-    const selectedStationForInput = useCallback(() => displayStationsRef.current[selectedRef.current] ?? null, []);
+    const selectedStationForInput = useCallback(() => {
+        const key = stationContextKeyForScreen(screenRef.current);
+        const stations = key ? applyStationFilters(stationContextsRef.current[key].stations, filters) : displayStationsRef.current;
+        return stations[selectedRef.current] ?? null;
+    }, [filters]);
     const alarmTui = useAlarmTui({
         service: alarmService,
         store,
         library,
         setLibrary,
         screen,
+        screenRef,
         selected,
+        selectedRef,
         setSelected,
         go,
         setMessage,
         playingStation,
-        previewStation: alarmPreview ?? (station => playStation(station))
+        previewStation: alarmPreview ?? (async (station) => { await playStation(station); })
     });
     for (const alarmScreen of ['alarms', 'alarm-editor', 'alarm-picker', 'alarm-ringing']) {
         itemCountsRef.current[alarmScreen] = alarmTui.itemCount(alarmScreen) ?? 0;
     }
     const openScreen = useCallback((target) => {
         if (target === 'explore') {
-            if (stationContextsRef.current.explore.stations.length > 0) {
-                go('explore');
-            }
-            else {
+            go('explore');
+            if (stationContextsRef.current.explore.stations.length === 0 && !loadingStationContextsRef.current.explore) {
                 void loadExplore();
             }
         }
         else if (target === 'nearby') {
-            if (stationContextsRef.current.nearby.stations.length > 0) {
-                go('nearby');
-            }
-            else {
+            go('nearby');
+            if (stationContextsRef.current.nearby.stations.length === 0 && !loadingStationContextsRef.current.nearby) {
                 void loadNearby();
             }
         }
@@ -1338,14 +1560,14 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
     }, [go, loadExplore, loadNearby, openAirPlaySettings, openLibrary]);
     const openAdjacentTab = useCallback((direction) => {
-        const active = activeTabForScreen(screen);
+        const active = activeTabForScreen(screenRef.current);
         const currentIndex = topTabs.findIndex(tab => tab.screen === active);
         const nextIndex = (currentIndex + direction + topTabs.length) % topTabs.length;
         const next = topTabs[nextIndex];
         if (next) {
             openScreen(next.screen);
         }
-    }, [openScreen, screen]);
+    }, [openScreen]);
     const handleUpdateCommand = useCallback(async () => {
         const updateCheck = library.updateCheck;
         if (!updateCheck || shouldCheckForUpdate(updateCheck)) {
@@ -1357,7 +1579,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             }
         }
         const command = updateCommandForInstall();
-        const copied = copyToClipboard(command.command);
+        const copied = await copyToClipboard(command.command);
         const latestVersion = store.snapshot().updateCheck?.latestVersion ?? updateCheck?.latestVersion;
         const prefix = latestVersion ? `Latest v${latestVersion}. ` : '';
         const method = command.method === 'homebrew' ? 'Homebrew' : command.method === 'npm' ? 'npm' : 'your install method';
@@ -1394,14 +1616,14 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 try {
                     const repaired = await mcpConfigurator(true, mcpRuntime(), null);
                     const suffix = repaired.some(item => item.status === 'failed') ? ' Some MCP clients need manual repair.' : ' MCP integrations repaired.';
-                    setMessage(`Update installed.${suffix} Restart RadioCLI and open agent clients.`);
+                    setMessage(`Update installed.${suffix} Quit and reopen RadioCLI; restart MCP clients to load updated tools.`);
                 }
                 catch {
-                    setMessage('Update installed. MCP repair failed; run radiocli mcp repair, then restart RadioCLI and open agent clients.');
+                    setMessage('Update installed. MCP repair failed; run radiocli mcp repair, then quit and reopen RadioCLI and restart MCP clients.');
                 }
             }
             else {
-                setMessage('Update installed. Restart RadioCLI to use the new version.');
+                setMessage('Update installed. Quit and reopen RadioCLI to use the new version.');
             }
             return;
         }
@@ -1410,17 +1632,21 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     }, [installedVersion, library.updateCheck, mcpConfigurator, refreshUpdateCheck, store]);
     const executeCommand = useCommandExecutor({
         beginLearningTransportKey,
+        cancelPendingTune,
         countries,
         go,
         loadCountry,
         openAirPlaySettings,
+        openAirPlayCode,
         openLibrary,
+        persistLibrary,
         player,
         playingStation,
         providers,
         resetLearnedTransportKeys,
         runSearch,
         screen,
+        screenRef,
         selectedStation,
         setCountries,
         setFilters,
@@ -1459,11 +1685,13 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             void playStation(nextStation, { queue });
         }
     }, [playStation, playingStation, queueContainsStation, queueFromCurrentList, rememberQueueSelection]);
-    agentHandlerRef.current = async (command) => {
+    agentHandlerRef.current = async (command, signal) => {
         const sessionStatus = () => ({
             owner: 'tui',
             playback: player.getState(),
             station: playingStationRef.current,
+            nowPlaying: engine.snapshot().nowPlaying,
+            persistenceWarning: persistenceWarning ?? engine.snapshot().warning,
             queue: playbackQueueRef.current?.stations ?? [],
             output: {
                 preferredBackend: settingsRef.current.preferredBackend,
@@ -1471,6 +1699,13 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             }
         });
         const respond = (message, ok = true, data) => ({ ok, message, status: sessionStatus(), ...(data ? { data } : {}) });
+        if (command.type === 'desktop-transport') {
+            const resolved = resolveDesktopTransport(command.action, sessionStatus());
+            return resolved ? agentHandlerRef.current(resolved, signal) : respond('Playback state unchanged.');
+        }
+        if (['airplay-list', 'airplay-select', 'airplay-passcode'].includes(command.type) && !airPlaySupported) {
+            return respond(airPlayUnavailableMessage, false, command.type === 'airplay-list' ? [] : undefined);
+        }
         if (command.type === 'status')
             return respond(playingStationRef.current ? `${player.getState().state}: ${playingStationRef.current.name}` : 'RadioCLI is idle.');
         if (command.type === 'play') {
@@ -1478,28 +1713,37 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 return respond(`Kept current station ${playingStationRef.current?.name ?? ''}.`);
             }
             const queue = { title: 'Agent selection', sourceScreen: 'now-playing', sourceContextKey: null, stations: command.queue?.length ? command.queue : [command.station] };
-            await playStation(command.station, { queue, openNowPlaying: command.openNowPlaying });
+            const tuned = await playStation(command.station, { queue, openNowPlaying: command.openNowPlaying, signal });
             const state = player.getState();
-            const playingRequestedStation = playingStationRef.current
-                && stationKey(playingStationRef.current) === stationKey(command.station)
+            const playingRequestedStation = tuned && playingStationRef.current
+                && stationKey(playingStationRef.current) === stationKey(tuned)
                 && state.state === 'playing'
                 && state.ready;
             return playingRequestedStation
-                ? respond(`Playing ${command.station.name}.`)
+                ? respond(`Playing ${tuned.name}.`)
                 : respond(state.state === 'error' ? state.message ?? `Could not play ${command.station.name}.` : `Could not play ${command.station.name}.`, false);
         }
         if (command.type === 'pause') {
-            const control = await player.pause();
+            const control = await engine.pause();
             return respond(control.message ?? 'Paused.', control.ok);
         }
         if (command.type === 'resume') {
-            const control = await player.resume();
+            const station = playingStationRef.current;
+            if (command.restartStopped && station && ['idle', 'stopped'].includes(player.getState().state)) {
+                await playStation(station, { queue: playbackQueueRef.current ?? queueFromCurrentList(station), signal });
+                return respond(`Playing ${station.name}.`, player.getState().ready && player.getState().state === 'playing');
+            }
+            const control = await engine.resume();
             return respond(control.message ?? 'Resumed.', control.ok);
         }
         if (command.type === 'stop') {
-            tuneRequestRef.current += 1;
-            setLibrary(store.finishActiveListeningSession());
-            await player.stop();
+            cancelPendingTune();
+            await engine.stop({ retainSelection: command.retainSelection });
+            if (command.retainSelection) {
+                setTuningStation(null);
+                desktopMediaRef.current?.refresh();
+                return respond('Stopped playback.');
+            }
             playingStationRef.current = null;
             setPlayingStation(null);
             setTuningStation(null);
@@ -1507,9 +1751,10 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             return respond('Stopped RadioCLI.');
         }
         if (command.type === 'alarm-preempt') {
-            tuneRequestRef.current += 1;
-            setLibrary(store.finishActiveListeningSession());
-            await player.stop();
+            desktopSuspendedRef.current = true;
+            desktopMediaRef.current?.refresh();
+            cancelPendingTune();
+            await engine.stop();
             playingStationRef.current = null;
             setPlayingStation(null);
             setTuningStation(null);
@@ -1517,9 +1762,16 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             return respond('Interactive playback yielded to the alarm.');
         }
         if (command.type === 'set-volume') {
-            const control = await player.setVolume(clampVolume(command.volume));
+            const control = command.unmute
+                ? await player.setVolume(clampVolume(command.volume), { allowStopped: true })
+                : await player.setVolume(clampVolume(command.volume));
             if (control.ok)
-                updateSettings({ volume: player.getState().volume });
+                await updateSettings({ volume: player.getState().volume });
+            if (control.ok && command.unmute && command.volume > 0) {
+                const unmuted = await player.setMuted(false, { allowStopped: true });
+                if (!unmuted.ok)
+                    return respond(unmuted.message ?? 'The output could not be unmuted.', false);
+            }
             return respond(control.message ?? `Volume ${player.getState().volume}.`, control.ok);
         }
         if (command.type === 'set-muted') {
@@ -1532,15 +1784,36 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 return respond('No active station to favorite.', false);
             const current = store.isFavorite(station);
             if (current !== command.favorite)
-                toggleFavorite(station);
+                await toggleFavorite(station);
             return respond(`${command.favorite ? 'Favorited' : 'Removed favorite'}: ${station.name}.`);
         }
         if (command.type === 'airplay-list') {
-            const devices = await refreshAirPlayTargets(false);
+            if (networkPolicy().offline)
+                return respond('AirPlay discovery is disabled by RADIOCLI_OFFLINE=1.', false, []);
+            let devices;
+            try {
+                devices = await refreshAirPlayTargets(false);
+            }
+            catch (error) {
+                if (error instanceof PlaybackOutputError)
+                    return respond(error.message, false, []);
+                throw error;
+            }
             return respond(devices.length ? `${devices.length} AirPlay receiver(s) found.` : 'No AirPlay receivers found.', true, devices);
         }
         if (command.type === 'airplay-select') {
-            const devices = await refreshAirPlayTargets(false);
+            if (networkPolicy().offline)
+                return respond('AirPlay discovery is disabled by RADIOCLI_OFFLINE=1.', false);
+            let devices;
+            try {
+                devices = await refreshAirPlayTargets(false);
+            }
+            catch (error) {
+                if (error instanceof PlaybackOutputError)
+                    return respond(error.message, false, []);
+                throw error;
+            }
+            signal?.throwIfAborted();
             const device = devices.find(item => item.id === command.deviceId);
             if (!device)
                 return respond('AirPlay receiver not found. Refresh and use an exact receiver ID.', false, devices);
@@ -1548,18 +1821,19 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 const backend = preferredLocalPlaybackBackend(availableBackends);
                 if (!backend)
                     return respond('No local playback backend is available. Run radiocli setup to install mpv.', false);
-                updateSettings({ preferredBackend: backend });
+                await updateSettings({ preferredAirPlayDevice: device.id, preferredBackend: backend });
+                signal?.throwIfAborted();
                 if (playingStationRef.current && shouldRetuneForAudioOutput(player.getState().state)) {
-                    await playStation(playingStationRef.current, { queue: playbackQueueRef.current ?? queueFromCurrentList(playingStationRef.current) });
+                    await playStation(playingStationRef.current, { queue: playbackQueueRef.current ?? queueFromCurrentList(playingStationRef.current), signal });
                 }
                 return respond(`Audio output set to this device (${backend}).`);
             }
             if (!isAirPlayBackendAvailable(availableBackends))
                 return respond('AirPlay playback is unavailable; run radiocli doctor.', false);
-            updateSettings({ preferredAirPlayDevice: device.id });
-            updateSettings({ preferredBackend: 'airplay' });
+            await updateSettings({ preferredAirPlayDevice: device.id, preferredBackend: 'airplay' });
+            signal?.throwIfAborted();
             if (playingStationRef.current && shouldRetuneForAudioOutput(player.getState().state)) {
-                await playStation(playingStationRef.current, { queue: playbackQueueRef.current ?? queueFromCurrentList(playingStationRef.current) });
+                await playStation(playingStationRef.current, { queue: playbackQueueRef.current ?? queueFromCurrentList(playingStationRef.current), signal });
             }
             return respond(`Audio output set to AirPlay receiver ${device.name}.`);
         }
@@ -1567,20 +1841,26 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             const backend = preferredLocalPlaybackBackend(availableBackends);
             if (!backend)
                 return respond('No local playback backend is available. Run radiocli setup to install mpv.', false);
-            updateSettings({ preferredBackend: backend });
+            await updateSettings({ preferredBackend: backend });
+            signal?.throwIfAborted();
             if (playingStationRef.current && shouldRetuneForAudioOutput(player.getState().state)) {
-                await playStation(playingStationRef.current, { queue: playbackQueueRef.current ?? queueFromCurrentList(playingStationRef.current) });
+                await playStation(playingStationRef.current, { queue: playbackQueueRef.current ?? queueFromCurrentList(playingStationRef.current), signal });
             }
             return respond(`Audio output set to this device (${backend}).`);
         }
         if (command.type === 'airplay-passcode') {
-            const control = player.submitAirPlayPasscode(command.code);
+            const control = await player.submitAirPlayPasscode(command.code);
             return respond(control.message ?? 'AirPlay code sent.', control.ok);
         }
         if (command.type === 'update-settings') {
-            updateSettings(command.settings);
+            if (!allowedRadioSessionSettings(command.settings))
+                return respond('Session settings only accept appearance and agent control. Use radiocli setup --airplay to enable Linux AirPlay.', false);
+            await updateSettings(command.settings);
             return respond('RadioCLI settings updated.');
         }
+        if (command.type !== 'next' && command.type !== 'previous')
+            throw new Error('Unsupported radio command.');
+        signal?.throwIfAborted();
         const active = playingStationRef.current;
         const queue = playbackQueueRef.current;
         if (!active || !queue?.stations.length)
@@ -1590,33 +1870,80 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         const next = queue.stations[(Math.max(0, currentIndex) + delta + queue.stations.length) % queue.stations.length];
         if (!next)
             return respond('No adjacent station is available.', false);
-        await playStation(next, { queue });
-        return respond(`Playing ${next.name}.`);
+        if (command.preserveStop && ['idle', 'stopped'].includes(player.getState().state)) {
+            engine.select(next, queue.stations);
+            playingStationRef.current = next;
+            setPlayingStation(next);
+            setNowPlaying(null);
+            desktopMediaRef.current?.refresh();
+            return respond(`Selected ${next.name}.`);
+        }
+        const startPaused = command.preservePause && player.getState().state === 'paused';
+        await playStation(next, { queue, startPaused, signal });
+        const state = player.getState();
+        const ok = playingStationRef.current && stationKey(playingStationRef.current) === stationKey(next) && state.ready && ['playing', 'paused'].includes(state.state);
+        return respond(`${startPaused ? 'Selected' : 'Playing'} ${next.name}.`, Boolean(ok));
     };
+    activeAlarmRef.current = alarmTui.activeAlarms.length > 0;
+    useEffect(() => {
+        if (playbackSession || !stdin.isTTY || !desktopPolicy.enabled || !controlSessionReady)
+            return;
+        const media = startDesktopMediaControls({
+            player, identity: store.filePath, policy: desktopPolicy,
+            status: () => ({ owner: 'tui', playback: player.getState(), station: playingStationRef.current, queue: playbackQueueRef.current?.stations ?? [] }),
+            command: (command, permitted) => dispatchOwnerCommand(command, () => permitted?.() !== false && !desktopSuspendedRef.current && !activeAlarmRef.current),
+            suspended: () => desktopSuspendedRef.current || activeAlarmRef.current
+        });
+        desktopMediaRef.current = media;
+        return () => { media.close(); if (desktopMediaRef.current === media)
+            desktopMediaRef.current = null; };
+    }, [controlSessionReady, desktopPolicy, dispatchOwnerCommand, player, stdin, store, playbackSession]);
+    useEffect(() => { desktopMediaRef.current?.refresh(); }, [alarmTui.activeAlarms.length]);
     useEffect(() => {
-        if (!stdin.isTTY || !(settingsRef.current.agentControl ?? defaultAgentControlSettings).enabled)
+        if (!stdin.isTTY)
             return;
+        if (playbackSession) {
+            if (initialAgentCommand && (settingsRef.current.agentControl ?? defaultAgentControlSettings).enabled) {
+                void playbackSession.call(initialAgentCommand).catch(reportActionError);
+            }
+            return;
+        }
         let disposed = false;
         let close;
-        void startRadioSession(command => agentHandlerRef.current(command)).then(async (session) => {
+        void startRadioSession(async (command, source) => {
+            const permitted = async () => {
+                if (source !== 'cli' && command.type !== 'status' && command.type !== 'alarm-preempt')
+                    await store.readFresh();
+                if (disposed)
+                    throw new Error('RadioCLI control session is closed.');
+                if (source !== 'cli' && !(settingsRef.current.agentControl ?? defaultAgentControlSettings).enabled && command.type !== 'status' && command.type !== 'alarm-preempt') {
+                    throw new Error('Agent controls are disabled.');
+                }
+                return true;
+            };
+            return dispatchOwnerCommand(command, permitted);
+        }, undefined, { queue: 'owner' }).then(async (session) => {
             if (disposed) {
                 await session.close();
                 return;
             }
             close = session.close;
-            if (initialAgentCommand)
-                await agentHandlerRef.current(initialAgentCommand);
+            setControlSessionReady(true);
+            if (initialAgentCommand && (settingsRef.current.agentControl ?? defaultAgentControlSettings).enabled)
+                await dispatchOwnerCommand(initialAgentCommand);
         }).catch(error => setMessage(error instanceof Error ? error.message : 'Agent controls could not start.'));
         return () => {
             disposed = true;
+            setControlSessionReady(false);
             if (close)
                 void close();
         };
-    }, [initialAgentCommand, library.settings.agentControl?.enabled, stdin]);
+    }, [dispatchOwnerCommand, initialAgentCommand, stdin, store, playbackSession, reportActionError]);
     useAppInput({
         adjustVolume,
         airPlayCode,
         canEnterAirPlayCode,
+        airPlaySupported,
         cancelPendingAutoSkip,
         copyStationUrl,
         openStationHomepage,
@@ -1656,7 +1983,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         moveExploreCursorToCell: moveExploreMapCursorToCell,
         refreshProviderHealth,
         refreshAirPlayTargets: () => {
-            void refreshAirPlayTargets();
+            void refreshAirPlayTargets().catch(reportActionError);
         },
         resetLearnedTransportKeys,
         repairMcpIntegrations,
@@ -1664,7 +1991,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         runSearch,
         saveLearnedTransportKey,
         screen,
-        settingsPage,
+        screenRef,
+        settingsPageRef,
         searchQuery,
         selectedRef,
         selectedStationForInput,
@@ -1711,6 +2039,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         spinnerFrame
     });
     const basePageFooter = pageFooterText({
+        airPlaySupported,
         canEnterAirPlayCode,
         capturingTransportAction,
         commandMode,
@@ -1730,7 +2059,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         (screen === 'search' && editingSearch) ||
         screen === 'airplay-code');
     const hasActiveMicroPlayback = Boolean(footerStation && (footerPlayback.state === 'playing' || footerPlayback.state === 'paused'));
-    const microFooter = footerMessage ?? message ?? (pageFooterOwnsCompactRow
+    const statusMessage = message ?? persistenceWarning ?? presenceWarning ?? (screen === 'search' ? stationContext.error ?? null : null);
+    const microFooter = footerMessage ?? statusMessage ?? (pageFooterOwnsCompactRow
         ? pageFooter
         : footerPlayback.state === 'loading' && playbackFooter
             ? playbackFooter
@@ -1739,17 +2069,17 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                 : pageFooter);
     const compactGlobalFooter = '←/→ tabs · ? help · q quit';
     const versionReserve = versionIndicatorWidth(installedVersion, library.updateCheck) + 2;
-    const fullStatusRows = fullStatusFooterRows(screen, message, footerMessage, playbackFooter);
-    const fullLegendRows = balancedFooterLegendRows(pageFooter, globalFooter, frameWidth, 2, versionReserve);
-    const compactStatus = footerMessage ?? message ?? playbackFooter;
+    const fullStatusRows = fullStatusFooterRows(screen, statusMessage, footerMessage, playbackFooter);
+    const fullLegendRows = useMemo(() => balancedFooterLegendRows(pageFooter, globalFooter, frameWidth, 2, versionReserve), [pageFooter, globalFooter, frameWidth, versionReserve]);
+    const compactStatus = footerMessage ?? statusMessage ?? playbackFooter;
     const compactLegendRowCount = Math.max(1, layout.footerRows - (compactStatus ? 1 : 0));
-    const compactLegendRows = balancedFooterLegendRows(pageFooter, compactGlobalFooter, frameWidth, compactLegendRowCount, versionReserve);
+    const compactLegendRows = useMemo(() => balancedFooterLegendRows(pageFooter, compactGlobalFooter, frameWidth, compactLegendRowCount, versionReserve), [pageFooter, compactGlobalFooter, frameWidth, compactLegendRowCount, versionReserve]);
     const microLegendWidth = Math.max(1, frameWidth - versionReserve);
-    const microLegend = commandMode || capturingTransportAction || footerMessage || message
+    const microLegend = commandMode || capturingTransportAction || footerMessage || statusMessage
         ? microFooter
         : microShortcutFooterText(microFooter, microLegendWidth);
     const footerText = (value) => displayMode.ascii ? toAsciiSafe(value) : value;
-    return (_jsx(ReceiverAnimationProvider, { screen: screen, playback: playback, receiverStyle: library.settings.receiverStyle, reduceMotion: Boolean(library.settings.reduceMotion), children: _jsx(DisplayContext.Provider, { value: displayMode, children: _jsxs(Box, { flexDirection: "column", paddingX: layout.horizontalPadding, height: layout.rows, width: layout.columns, overflow: "hidden", backgroundColor: displayMode.app, children: [hasTopTabs ? (_jsx(Box, { height: 3, flexShrink: 0, backgroundColor: displayMode.app, children: _jsx(TopTabs, { tabs: topTabs, active: activeTabForScreen(screen), theme: theme, width: frameWidth, backendLabel: playbackBackendLabel(playback.backend) }) })) : null, _jsx(Box, { height: layout.contentRows, width: frameWidth, flexDirection: "column", overflowY: "hidden", flexShrink: 0, backgroundColor: displayMode.app, children: _jsx(AppContent, { airPlayDevices: availableAirPlayDevices, airPlayCode: airPlayCode, appVersion: installedVersion, backends: availableBackends, countryFilter: countryFilter, diagnostics: diagnostics, displayStations: displayStations, editingCountryFilter: editingCountryFilter, editingSearch: editingSearch, favoriteKeys: favoriteKeys, filterLabel: filterLabel, filteredCountries: filteredCountries, frameWidth: frameWidth, layout: layout, library: library, loadingCountries: loadingCountries, loadingStations: loadingStations, nowPlaying: nowPlaying, playback: footerPlayback, playingStation: footerStation, providerHealth: providerHealth, searchQuery: searchQuery, screen: screen, settingsPage: settingsPage, selected: selected, showDiagnostics: showDiagnostics, sleepLabel: sleepLabel, stationContext: stationContext, exploreCursor: exploreCursor, stationFavorite: store.isFavorite(footerStation), stationTime: stationApproximateTime(footerStation), storePath: store.filePath, theme: theme, updateCheck: library.updateCheck, alarmTui: alarmTui }) }), _jsx(Box, { height: layout.footerRows, width: frameWidth, flexDirection: "column", flexShrink: 0, backgroundColor: displayMode.app, children: layout.mode === 'full' ? (_jsxs(_Fragment, { children: [fullStatusRows.map(statusRow => (_jsx(Text, { color: themeAccent(theme), children: footerText(truncate(statusRow.text, frameWidth)) }, statusRow.key))), _jsx(Text, { color: commandMode || capturingTransportAction ? themeAccent(theme) : textMuted, children: footerText(fullLegendRows[0] ?? ' ') }), _jsxs(Box, { children: [_jsx(Text, { color: textDim, children: footerText(fullLegendRows[1] ?? ' ') }), _jsx(Box, { flexGrow: 1 }), _jsx(VersionIndicator, { currentVersion: installedVersion, updateCheck: library.updateCheck, theme: theme })] })] })) : (_jsx(_Fragment, { children: layout.mode === 'micro' ? _jsxs(Box, { children: [_jsx(Text, { color: commandMode || capturingTransportAction || footerMessage || message ? themeAccent(theme) : textMuted, children: footerText(truncate(microLegend, microLegendWidth)) }), _jsx(Box, { flexGrow: 1 }), _jsx(VersionIndicator, { currentVersion: installedVersion, updateCheck: library.updateCheck, theme: theme })] }) : _jsxs(_Fragment, { children: [compactStatus ? _jsx(Text, { color: footerMessage || message ? themeAccent(theme) : textMuted, children: footerText(truncate(compactStatus, frameWidth)) }) : null, compactLegendRows.map((row, index) => index === compactLegendRows.length - 1 ? _jsxs(Box, { children: [_jsx(Text, { color: textDim, children: footerText(row) }), _jsx(Box, { flexGrow: 1 }), _jsx(VersionIndicator, { currentVersion: installedVersion, updateCheck: library.updateCheck, theme: theme })] }, `legend-${index}`) : _jsx(Text, { color: index === 0 ? textMuted : textDim, children: footerText(row) }, `legend-${index}`))] }) })) })] }) }) }));
+    return (_jsx(ReceiverAnimationProvider, { screen: screen, playback: playback, receiverStyle: library.settings.receiverStyle, reduceMotion: displayMode.reduceMotion, children: _jsx(DisplayContext.Provider, { value: displayMode, children: _jsxs(Box, { flexDirection: "column", paddingX: layout.horizontalPadding, height: layout.rows, width: layout.columns, overflow: "hidden", backgroundColor: displayMode.app, children: [hasTopTabs ? (_jsx(Box, { height: 3, flexShrink: 0, backgroundColor: displayMode.app, children: _jsx(TopTabs, { tabs: topTabs, active: activeTabForScreen(screen), theme: theme, width: frameWidth, backendLabel: playbackBackendLabel(playback.backend) }) })) : null, _jsx(Box, { height: layout.contentRows, width: frameWidth, flexDirection: "column", overflowY: "hidden", flexShrink: 0, backgroundColor: displayMode.app, children: _jsx(AppContent, { platform: platform, airPlayDevices: availableAirPlayDevices, airPlaySupported: airPlaySupported, airPlayCode: airPlayCode, appVersion: installedVersion, backends: availableBackends, countryFilter: countryFilter, diagnostics: diagnostics, displayStations: displayStations, editingCountryFilter: editingCountryFilter, editingSearch: editingSearch, favoriteKeys: favoriteKeys, filterLabel: filterLabel, filteredCountries: filteredCountries, frameWidth: frameWidth, layout: layout, library: library, loadingCountries: loadingCountries, loadingStations: loadingStations, nowPlaying: nowPlaying, playback: footerPlayback, playingStation: footerStation, providerHealth: providerHealth, searchQuery: searchQuery, screen: screen, settingsPage: settingsPage, selected: selected, showDiagnostics: showDiagnostics, sleepLabel: sleepLabel, stationContext: stationContext, exploreCursor: exploreCursor, stationFavorite: store.isFavorite(footerStation), stationTime: stationApproximateTime(footerStation), storePath: store.filePath, theme: theme, updateCheck: library.updateCheck, alarmTui: alarmTui }) }), _jsx(Box, { height: layout.footerRows, width: frameWidth, flexDirection: "column", flexShrink: 0, backgroundColor: displayMode.app, children: layout.mode === 'full' ? (_jsxs(_Fragment, { children: [fullStatusRows.map(statusRow => (_jsx(Text, { color: themeAccent(theme), children: footerText(truncate(statusRow.text, frameWidth)) }, statusRow.key))), _jsx(Text, { color: commandMode || capturingTransportAction ? themeAccent(theme) : textMuted, children: footerText(fullLegendRows[0] ?? ' ') }), _jsxs(Box, { children: [_jsx(Text, { color: textDim, children: footerText(fullLegendRows[1] ?? ' ') }), _jsx(Box, { flexGrow: 1 }), _jsx(VersionIndicator, { currentVersion: installedVersion, updateCheck: library.updateCheck, theme: theme })] })] })) : (_jsx(_Fragment, { children: layout.mode === 'micro' ? _jsxs(Box, { children: [_jsx(Text, { color: commandMode || capturingTransportAction || footerMessage || statusMessage ? themeAccent(theme) : textMuted, children: footerText(truncate(microLegend, microLegendWidth)) }), _jsx(Box, { flexGrow: 1 }), _jsx(VersionIndicator, { currentVersion: installedVersion, updateCheck: library.updateCheck, theme: theme })] }) : _jsxs(_Fragment, { children: [compactStatus ? _jsx(Text, { color: footerMessage || statusMessage ? themeAccent(theme) : textMuted, children: footerText(truncate(compactStatus, frameWidth)) }) : null, compactLegendRows.map((row, index) => index === compactLegendRows.length - 1 ? _jsxs(Box, { children: [_jsx(Text, { color: textDim, children: footerText(row) }), _jsx(Box, { flexGrow: 1 }), _jsx(VersionIndicator, { currentVersion: installedVersion, updateCheck: library.updateCheck, theme: theme })] }, `legend-${index}`) : _jsx(Text, { color: index === 0 ? textMuted : textDim, children: footerText(row) }, `legend-${index}`))] }) })) })] }) }) }));
 }
 function mcpRuntime() {
     return { nodePath: process.execPath, cliPath: fileURLToPath(new URL('../cli.js', import.meta.url)) };
@@ -1777,12 +2107,12 @@ function buildLibraryStations(library) {
     for (const station of library.favorites) {
         addStation(station);
     }
-    for (const item of library.recent) {
-        addStation(item.station);
-    }
     for (const station of library.imported) {
         addStation(station);
     }
+    for (const item of library.recent) {
+        addStation(item.station);
+    }
     return stations;
 }
 function exploreCursorLocation(cursor) {
@@ -1804,6 +2134,10 @@ function appendUniqueStations(current, page) {
     }
     return stations;
 }
+function discoverySourceWarning(sources) {
+    const unavailable = [...new Set(sources.filter(source => source.status === 'unavailable').map(source => source.provider === 'radio-browser' ? 'Radio Browser' : source.provider === 'radio-garden' ? 'Radio Garden' : source.provider))];
+    return unavailable.length ? `Some sources are unavailable (${unavailable.join(', ')}). Showing available results.` : undefined;
+}
 function formatCountryStationsSubtitle(country, loaded, hasMore) {
     const total = country.stationCount.toLocaleString();
     const loadedLabel = loaded.toLocaleString();
@@ -1880,7 +2214,7 @@ function audioOutputSwitchLabel(output, backends) {
     return audioOutputLabel(output);
 }
 function librarySubtitle(library) {
-    return `${library.favorites.length} favorites · ${library.recent.length} recent · ${library.imported.length} imported · favorites first`;
+    return `${library.favorites.length} favorites · ${library.imported.length} imported · ${library.recent.length} recent · new imports before recents`;
 }
 function mouseVisibleRows(screen, layout) {
     if (screen === 'help')
@@ -1907,3 +2241,10 @@ function mouseVisibleRows(screen, layout) {
         return layout.stationRows;
     return layout.contentRows;
 }
+function localSessionLibrary(library, platform, selectionRequired = true) {
+    return platform === 'linux' && selectionRequired && library.settings.preferredBackend === 'airplay'
+        ? { ...library, settings: { ...library.settings, preferredBackend: 'auto' } } : library;
+}
+function legacyDiscoveryPage(items, limit) {
+    return { items, exhausted: items.length < limit, sources: [] };
+}