@ciphore/radiocli 0.2.3 → 0.2.4

package/dist/ui/App.js

@@ -1,10 +1,10 @@
 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 { airPlayMacOSOnlyMessage, isAirPlayPlatformSupported, playbackBackendInstallHint, playbackBackendLabel } from '../player/backend-install.js';
 import { JsonLibraryStore, stationKey } from '../storage/store.js';
 import { defaultAgentControlSettings } from '../types.js';
 import { nextReceiverStyle, nextTheme, textDim, textMuted, themeAccent } from './theme.js';
@@ -21,8 +21,10 @@ 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';
@@ -37,7 +39,7 @@ import { activeTabForScreen, addMediaKeyBinding, applyStationFilters, clamp, cla
 import { ReceiverAnimationProvider } from './receiver-animation.js';
 import { VersionIndicator, versionIndicatorWidth } from './components/VersionIndicator.js';
 const LOADING_SPINNER_MS = 120;
-const VISUALIZER_MESSAGE_MS = 4500;
+const TRANSIENT_NOTICE_MS = 4500;
 const LISTENING_HEARTBEAT_MS = 30_000;
 const COUNTRY_STATIONS_PAGE_SIZE = 120;
 const COUNTRY_STATIONS_LOAD_AHEAD = 12;
@@ -52,15 +54,17 @@ 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 }) {
     const { exit } = useApp();
     const { stdin } = useStdin();
     const { stdout } = useStdout();
     const { columns, rows } = useWindowSize();
+    const screenReader = useIsScreenReaderEnabled();
     const store = useMemo(() => providedStore ?? new JsonLibraryStore(), [providedStore]);
     const providers = useMemo(() => providedProviders ?? new ProviderManager(), [providedProviders]);
     const alarmService = useMemo(() => providedAlarmService ? serializeAlarmTuiService(providedAlarmService) : createAlarmTuiService(), [providedAlarmService]);
     const installedVersion = useMemo(() => appVersion(), []);
+    const airPlaySupported = isAirPlayPlatformSupported(platform);
     const [library, setLibrary] = useState(() => store.snapshot());
     const settingsRef = useRef(library.settings);
     settingsRef.current = library.settings;
@@ -72,6 +76,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     const [selected, setSelected] = useState(0);
     const [settingsPage, setSettingsPage] = useState('root');
     const [message, setMessage] = useState(null);
+    const [persistenceWarning, setPersistenceWarning] = useState(null);
+    const [presenceWarning, setPresenceWarning] = useState(null);
     const [footerMessage, setFooterMessage] = useState(null);
     const [countries, setCountries] = useState([]);
     const [countryFilter, setCountryFilter] = useState('');
@@ -95,6 +101,23 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     const [sleepUntil, setSleepUntil] = useState(null);
     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((write) => {
+        try {
+            const nextLibrary = write();
+            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;
+        }
+    }, []);
     const announcedUpdateRef = useRef(false);
     const automaticUpdateCheckStartedRef = useRef(false);
     const installingUpdateRef = useRef(false);
@@ -132,8 +155,18 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
     const agentHandlerRef = useRef(async () => {
         throw new Error('RadioCLI is still starting.');
     });
+    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);
@@ -222,12 +255,31 @@ 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]);
+    useEffect(() => {
+        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.');
+                }
+            };
+        }
+        catch {
+            setPresenceWarning('Alarm controls cannot register this terminal in the runtime directory. Browsing and playback remain available.');
+        }
+    }, [stdin]);
     const playingStationRef = useRef(null);
     playingStationRef.current = playingStation;
     const activeListeningStationRef = useRef(null);
@@ -239,24 +291,24 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             const key = stationKey(station);
             if (activeListeningStationRef.current !== key) {
                 activeListeningStationRef.current = key;
-                setLibrary(store.startListeningSession(station));
+                persistLibrary(() => store.startListeningSession(station));
             }
             return;
         }
         if (activeListeningStationRef.current) {
             activeListeningStationRef.current = null;
-            setLibrary(store.finishActiveListeningSession());
+            persistLibrary(() => store.finishActiveListeningSession());
         }
-    }, [playback.ready, playback.state, playingStation, store]);
+    }, [persistLibrary, playback.ready, playback.state, playingStation, store]);
     useEffect(() => {
         if (playback.state !== 'playing' || !playback.ready || !playingStation) {
             return;
         }
         const timer = setInterval(() => {
-            setLibrary(store.checkpointActiveListeningSession());
+            persistLibrary(() => store.checkpointActiveListeningSession());
         }, LISTENING_HEARTBEAT_MS);
         return () => clearInterval(timer);
-    }, [playback.ready, playback.state, playingStation, store]);
+    }, [persistLibrary, playback.ready, playback.state, playingStation, store]);
     useEffect(() => player.onMetadata(metadata => {
         setNowPlaying(metadata);
         const station = playingStationRef.current;
@@ -265,9 +317,9 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             if (lastRecordedTrackRef.current === trackKey)
                 return;
             lastRecordedTrackRef.current = trackKey;
-            setLibrary(store.recordTrack(station, metadata.title));
+            persistLibrary(() => store.recordTrack(station, metadata.title));
         }
-    }), [player, store]);
+    }), [persistLibrary, player, store]);
     useEffect(() => {
         if (!stdout.isTTY || !mouseReportingActive) {
             return;
@@ -285,7 +337,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 +345,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 &&
@@ -332,27 +384,30 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         const delayMs = sleepUntil - Date.now();
         if (delayMs <= 0) {
             tuneRequestRef.current += 1;
-            setLibrary(store.finishActiveListeningSession());
-            void player.stop();
+            persistLibrary(() => store.finishActiveListeningSession());
+            void player.stop().catch(reportActionError);
             setSleepUntil(null);
             return;
         }
         const timer = setTimeout(() => {
             tuneRequestRef.current += 1;
-            setLibrary(store.finishActiveListeningSession());
-            void player.stop();
+            persistLibrary(() => store.finishActiveListeningSession());
+            void player.stop().catch(reportActionError);
             setSleepUntil(null);
         }, delayMs);
         return () => clearTimeout(timer);
-    }, [player, sleepUntil, store]);
+    }, [persistLibrary, player, reportActionError, sleepUntil, store]);
     useEffect(() => {
         const backends = player.refreshDetectedBackends();
         setAvailableBackends(backends);
-        void player.refreshAirPlayDevices().then(setAvailableAirPlayDevices).catch(() => setAvailableAirPlayDevices([]));
+        const network = networkPolicy();
+        if (airPlaySupported && !network.offline && !network.lowBandwidth) {
+            void player.refreshAirPlayDevices().then(setAvailableAirPlayDevices).catch(() => setAvailableAirPlayDevices([]));
+        }
         if (backends.length === 0) {
             setMessage(`No playback backend found. ${playbackBackendInstallHint()}`);
         }
-    }, [player]);
+    }, [airPlaySupported, player]);
     const refreshProviderHealth = useCallback(() => {
         providers.health(settingsRef.current).then(setProviderHealth).catch(() => setProviderHealth({}));
     }, [providers]);
@@ -361,9 +416,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,11 +434,14 @@ 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) => {
         setStationContexts(current => ({ ...current, [key]: context }));
     }, []);
@@ -393,6 +451,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         const nextLibrary = store.updateSettings(settings);
         settingsRef.current = nextLibrary.settings;
         setLibrary(nextLibrary);
+        setPersistenceWarning(null);
         return nextLibrary;
     }, [store]);
     useEffect(() => {
@@ -404,9 +463,14 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             setMessage(`${selectedAirPlayDevice.name} is this Mac. 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]);
+        try {
+            updateSettings({ preferredBackend });
+            setMessage(`${selectedAirPlayDevice.name} is this Mac. Audio output: ${audioOutputLabel(preferredBackend)}.`);
+        }
+        catch (error) {
+            reportActionError(error);
+        }
+    }, [availableBackends, reportActionError, selectedAirPlayDevice, updateSettings]);
     const updateMediaKeys = useCallback((mediaKeys) => {
         updateSettings({ mediaKeys: normalizeMediaKeyBindings(mediaKeys) });
     }, [updateSettings]);
@@ -466,9 +530,13 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         openSettingsPage('root');
     }, [go, openSettingsPage]);
     const openAirPlayCode = useCallback(() => {
+        if (!airPlaySupported) {
+            showTransientMessage(airPlayMacOSOnlyMessage);
+            return;
+        }
         setAirPlayCode('');
         go('airplay-code', { resetSelection: true, clearMessage: false });
-    }, [go]);
+    }, [airPlaySupported, go, showTransientMessage]);
     useEffect(() => {
         if (isAirPlayCodePromptActive(playback) && screenRef.current !== 'airplay-code') {
             openAirPlayCode();
@@ -476,13 +544,13 @@ 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]);
+        persistLibrary(() => store.finishActiveListeningSession());
+        void player.stop().catch(reportActionError).finally(exit);
+    }, [exit, persistLibrary, player, reportActionError, store]);
     useEffect(() => {
         const finishForSignal = () => {
-            store.finishActiveListeningSession();
-            void player.stop().finally(() => process.exit(0));
+            persistLibrary(() => store.finishActiveListeningSession());
+            void player.stop().catch(reportActionError).finally(() => process.exit(0));
         };
         process.once('SIGTERM', finishForSignal);
         process.once('SIGHUP', finishForSignal);
@@ -490,7 +558,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             process.off('SIGTERM', finishForSignal);
             process.off('SIGHUP', finishForSignal);
         };
-    }, [player, store]);
+    }, [persistLibrary, player, reportActionError, store]);
     const showStationContext = useCallback((context, next = 'stations', options = {}) => {
         setStationContextFor(stationContextKeyForScreen(next) ?? 'stations', context);
         go(next, { resetSelection: options.resetSelection ?? true, clearMessage: options.clearMessage });
@@ -692,7 +760,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             });
             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);
@@ -706,7 +774,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             if (requestId === searchRequestRef.current)
                 setLoadingStations(false);
         }
-    }, [filters, providers, searchQuery, setStationContextFor, store]);
+    }, [filters, persistLibrary, providers, searchQuery, setStationContextFor, store]);
     const loadMoreSearchResults = useCallback(async () => {
         const context = stationContextsRef.current.search;
         const query = context.query;
@@ -911,8 +979,8 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             setPlayingStation(station);
             setTuningStation(null);
             playbackQueueRef.current = queue;
-            const nextLibrary = store.addRecent(station);
-            if (screenRef.current === 'library') {
+            const nextLibrary = persistLibrary(() => store.addRecent(station));
+            if (nextLibrary && screenRef.current === 'library') {
                 const nextLibraryStations = applyStationFilters(buildLibraryStations(nextLibrary), filters);
                 const nextLibraryIndex = nextLibraryStations.findIndex(item => stationMatches(item, station));
                 if (nextLibraryIndex >= 0) {
@@ -920,7 +988,6 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
                     setSelected(nextLibraryIndex);
                 }
             }
-            setLibrary(nextLibrary);
             if (options.openNowPlaying) {
                 go('now-playing');
             }
@@ -946,7 +1013,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             setTuningStation(null);
             setMessage(message);
         }
-    }, [filters, go, player, providers, queueFromCurrentList, rememberQueueSelection, stationMatches, store]);
+    }, [filters, go, persistLibrary, player, providers, 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);
@@ -972,7 +1039,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         setTuningStation(null);
         setMessage('Auto-skip canceled. Choose a station and press Enter.');
     }, []);
-    const showTransientFooterMessage = useCallback((nextMessage, durationMs = VISUALIZER_MESSAGE_MS) => {
+    const showTransientFooterMessage = useCallback((nextMessage, durationMs = TRANSIENT_NOTICE_MS) => {
         if (transientFooterMessageTimerRef.current) {
             clearTimeout(transientFooterMessageTimerRef.current);
         }
@@ -998,31 +1065,37 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
         const wasFavorite = store.isFavorite(station);
         setLibrary(store.toggleFavorite(station));
+        setPersistenceWarning(null);
         const favoriteMessage = `${wasFavorite ? 'Removed from' : 'Added to'} favorites: ${station.name}`;
-        if (screenRef.current === 'library') {
+        if (screenRef.current === 'library' || screenRef.current === 'search') {
             showTransientFooterMessage(favoriteMessage);
         }
         else {
-            setMessage(favoriteMessage);
+            showTransientMessage(favoriteMessage);
         }
         if (!wasFavorite && settingsRef.current.shareDirectoryVotes) {
             // Best-effort upvote back to the directory; never blocks favoriting.
-            void providers.vote(station);
+            void providers.vote(station).catch(reportActionError);
         }
-    }, [providers, showTransientFooterMessage, store]);
+    }, [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,12 +1106,13 @@ 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);
@@ -1059,8 +1133,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,24 +1143,14 @@ 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 });
@@ -1125,6 +1189,15 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         setMessage(`Radio Browser favorite votes ${shareDirectoryVotes ? 'enabled' : 'disabled'}.`);
     }, [updateSettings]);
     const refreshAirPlayTargets = useCallback(async (announce = true) => {
+        if (!airPlaySupported) {
+            if (announce)
+                showTransientMessage(airPlayMacOSOnlyMessage);
+            return [];
+        }
+        if (networkPolicy().offline) {
+            setMessage('AirPlay discovery is disabled by RADIOCLI_OFFLINE=1.');
+            return [];
+        }
         try {
             const devices = await player.refreshAirPlayDevices();
             setAvailableAirPlayDevices(devices);
@@ -1147,13 +1220,17 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             }
             return [];
         }
-    }, [player]);
+    }, [airPlaySupported, player, showTransientMessage]);
     const openAirPlaySettings = useCallback(() => {
+        if (!airPlaySupported) {
+            showTransientMessage(airPlayMacOSOnlyMessage);
+            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]);
+    }, [airPlaySupported, availableAirPlayDevices, go, refreshAirPlayTargets, showTransientMessage]);
     const selectAirPlayDeviceAt = useCallback((index) => {
         const device = availableAirPlayDevices[index];
         if (!device) {
@@ -1357,7 +1434,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';
@@ -1415,6 +1492,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         loadCountry,
         openAirPlaySettings,
         openLibrary,
+        persistLibrary,
         player,
         playingStation,
         providers,
@@ -1471,6 +1549,9 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             }
         });
         const respond = (message, ok = true, data) => ({ ok, message, status: sessionStatus(), ...(data ? { data } : {}) });
+        if (['airplay-list', 'airplay-select', 'airplay-passcode'].includes(command.type) && !airPlaySupported) {
+            return respond(airPlayMacOSOnlyMessage, 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') {
@@ -1498,7 +1579,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
         if (command.type === 'stop') {
             tuneRequestRef.current += 1;
-            setLibrary(store.finishActiveListeningSession());
+            persistLibrary(() => store.finishActiveListeningSession());
             await player.stop();
             playingStationRef.current = null;
             setPlayingStation(null);
@@ -1508,7 +1589,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         }
         if (command.type === 'alarm-preempt') {
             tuneRequestRef.current += 1;
-            setLibrary(store.finishActiveListeningSession());
+            persistLibrary(() => store.finishActiveListeningSession());
             await player.stop();
             playingStationRef.current = null;
             setPlayingStation(null);
@@ -1536,10 +1617,14 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
             return respond(`${command.favorite ? 'Favorited' : 'Removed favorite'}: ${station.name}.`);
         }
         if (command.type === 'airplay-list') {
+            if (networkPolicy().offline)
+                return respond('AirPlay discovery is disabled by RADIOCLI_OFFLINE=1.', false, []);
             const devices = await refreshAirPlayTargets(false);
             return respond(devices.length ? `${devices.length} AirPlay receiver(s) found.` : 'No AirPlay receivers found.', true, devices);
         }
         if (command.type === 'airplay-select') {
+            if (networkPolicy().offline)
+                return respond('AirPlay discovery is disabled by RADIOCLI_OFFLINE=1.', false);
             const devices = await refreshAirPlayTargets(false);
             const device = devices.find(item => item.id === command.deviceId);
             if (!device)
@@ -1711,6 +1796,7 @@ export function App({ store: providedStore, providers: providedProviders, alarmS
         spinnerFrame
     });
     const basePageFooter = pageFooterText({
+        airPlaySupported,
         canEnterAirPlayCode,
         capturingTransportAction,
         commandMode,
@@ -1730,7 +1816,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;
+    const microFooter = footerMessage ?? statusMessage ?? (pageFooterOwnsCompactRow
         ? pageFooter
         : footerPlayback.state === 'loading' && playbackFooter
             ? playbackFooter
@@ -1739,17 +1826,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 fullStatusRows = fullStatusFooterRows(screen, statusMessage, footerMessage, playbackFooter);
     const fullLegendRows = balancedFooterLegendRows(pageFooter, globalFooter, frameWidth, 2, versionReserve);
-    const compactStatus = footerMessage ?? message ?? playbackFooter;
+    const compactStatus = footerMessage ?? statusMessage ?? playbackFooter;
     const compactLegendRowCount = Math.max(1, layout.footerRows - (compactStatus ? 1 : 0));
     const compactLegendRows = balancedFooterLegendRows(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, { 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 +1864,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) {
@@ -1880,7 +1967,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')