@ciphore/radiocli 0.1.4 → 0.1.6

package/dist/ui/App.js

@@ -6,7 +6,8 @@ import { PlayerController } from '../player/player-controller.js';
 import { playbackBackendInstallHint, playbackBackendLabel } from '../player/backend-install.js';
 import { JsonLibraryStore, stationKey } from '../storage/store.js';
 import { receiverStyleNames } from '../types.js';
-import { appBackground, nextReceiverStyle, nextTheme, panelBackground, textDim, themeAccent } from './theme.js';
+import { nextReceiverStyle, nextTheme, textDim, themeAccent } from './theme.js';
+import { DisplayContext, resolveDisplayMode } from './display-context.js';
 import { homeItems, settingsItems } from './screen-items.js';
 import { AppContent } from './AppContent.js';
 import { TopTabs } from './components/TopTabs.js';
@@ -20,11 +21,18 @@ import { useCommandExecutor } from './use-command-executor.js';
 import { isAirPlayCodePromptActive } from './screens/AirPlayCodeScreen.js';
 import { isAirPlayBackendAvailable } from './airplay-settings.js';
 import { audioOutputLabel, resolvedAudioOutput } from './audio-output.js';
+import { copyToClipboard, openExternal } from './system-actions.js';
 import { activeTabForScreen, addMediaKeyBinding, applyStationFilters, clamp, clampVolume, defaultExploreCursor, formatExploreCursor, formatFilterLabel, formatTimeLeft, initialStationContexts, mediaActionLabel, moveExploreCursor as shiftExploreCursor, nextSleepTimerMinutes, normalizeMediaKeyBindings, shouldAnimateReceiver, shouldSkipAfterTuneError, stationApproximateTime, stationContextKeyForScreen, topTabs } from './app-state.js';
 const LIVE_RECEIVER_STYLES = new Set(receiverStyleNames);
 const LIVE_RECEIVER_PULSE_MS = 80;
 const AMBIENT_RECEIVER_PULSE_MS = 140;
 const LOADING_SPINNER_MS = 120;
+const settingToggleLabel = {
+    resumeOnLaunch: 'Resume on launch',
+    transparentBackground: 'Transparent background',
+    asciiMode: 'ASCII-safe display',
+    reduceMotion: 'Reduce motion'
+};
 export function App({ store: providedStore, providers: providedProviders }) {
     const { exit } = useApp();
     const { stdin } = useStdin();
@@ -74,10 +82,12 @@ export function App({ store: providedStore, providers: providedProviders }) {
     const stationContextsRef = useRef(stationContexts);
     const lastStationContextKeyRef = useRef('explore');
     const lastSubmittedSearchRef = useRef('');
+    const searchHistoryRef = useRef({ cursor: -1, draft: '' });
     const exploreCursorRef = useRef(exploreCursor);
     const exploreRequestRef = useRef(0);
     const exploreMoveTimerRef = useRef(null);
     const theme = library.settings.theme;
+    const displayMode = useMemo(() => resolveDisplayMode(library.settings), [library.settings.transparentBackground, library.settings.asciiMode, library.settings.reduceMotion]);
     const favoriteKeys = useMemo(() => new Set(library.favorites.map(stationKey)), [library.favorites]);
     const diagnostics = player.diagnostics();
     const filterLabel = formatFilterLabel(filters);
@@ -124,7 +134,8 @@ export function App({ store: providedStore, providers: providedProviders }) {
         stats: 1,
         'airplay-settings': 0,
         'airplay-code': 1,
-        settings: settingsItems.length
+        settings: settingsItems.length,
+        help: 0
     });
     itemCountsRef.current = {
         home: homeItems.length,
@@ -139,7 +150,8 @@ export function App({ store: providedStore, providers: providedProviders }) {
         stats: 1,
         'airplay-settings': availableAirPlayDevices.length,
         'airplay-code': 1,
-        settings: settingsItems.length
+        settings: settingsItems.length,
+        help: 0
     };
     const displayStations = useMemo(() => applyStationFilters(stationContext.stations, filters), [filters, stationContext.stations]);
     displayStationsRef.current = displayStations;
@@ -151,7 +163,15 @@ export function App({ store: providedStore, providers: providedProviders }) {
     const layout = computeTerminalLayout(columns, rows, showPlaybackFooter ? 3 : 2);
     const frameWidth = Math.max(40, layout.columns - 2);
     useEffect(() => player.onChange(setPlayback), [player]);
-    useEffect(() => player.onMetadata(setNowPlaying), [player]);
+    const playingStationRef = useRef(null);
+    playingStationRef.current = playingStation;
+    useEffect(() => player.onMetadata(metadata => {
+        setNowPlaying(metadata);
+        const station = playingStationRef.current;
+        if (station && metadata.title) {
+            setLibrary(store.recordTrack(station, metadata.title));
+        }
+    }), [player, store]);
     useEffect(() => {
         if (screen !== 'explore' || layout.compact || !stdout.isTTY) {
             return;
@@ -169,6 +189,7 @@ export function App({ store: providedStore, providers: providedProviders }) {
     }, [renderedStationContextKey, screen, selected]);
     useEffect(() => {
         if (!shouldAnimateReceiver(screen, playback) ||
+            library.settings.reduceMotion ||
             process.env.RADIOCLI_DISABLE_ANIMATION === '1' ||
             process.env.RADIO_ATLAS_DISABLE_ANIMATION === '1') {
             return;
@@ -176,9 +197,10 @@ export function App({ store: providedStore, providers: providedProviders }) {
         const intervalMs = LIVE_RECEIVER_STYLES.has(library.settings.receiverStyle) ? LIVE_RECEIVER_PULSE_MS : AMBIENT_RECEIVER_PULSE_MS;
         const timer = setInterval(() => setPulse(value => (value + 1) % 240), intervalMs);
         return () => clearInterval(timer);
-    }, [library.settings.receiverStyle, playback.ready, playback.state, screen]);
+    }, [library.settings.receiverStyle, library.settings.reduceMotion, playback.ready, playback.state, screen]);
     useEffect(() => {
         if (playback.state !== 'loading' ||
+            library.settings.reduceMotion ||
             process.env.RADIOCLI_DISABLE_ANIMATION === '1' ||
             process.env.RADIO_ATLAS_DISABLE_ANIMATION === '1') {
             setSpinnerFrame(0);
@@ -186,7 +208,7 @@ export function App({ store: providedStore, providers: providedProviders }) {
         }
         const timer = setInterval(() => setSpinnerFrame(value => (value + 1) % 1000), LOADING_SPINNER_MS);
         return () => clearInterval(timer);
-    }, [playback.state]);
+    }, [library.settings.reduceMotion, playback.state]);
     useEffect(() => {
         if ((screen === 'countries' || screen === 'map') && countries.length === 0 && !loadingCountries) {
             setLoadingCountries(true);
@@ -420,6 +442,8 @@ export function App({ store: providedStore, providers: providedProviders }) {
             });
             selectedByScreenRef.current.search = 0;
             lastSubmittedSearchRef.current = query.trim();
+            setLibrary(store.addSearch(query));
+            searchHistoryRef.current = { cursor: -1, draft: '' };
             setSelected(0);
             setEditingSearch(true);
         }
@@ -429,7 +453,29 @@ export function App({ store: providedStore, providers: providedProviders }) {
         finally {
             setLoadingStations(false);
         }
-    }, [filters, providers, searchQuery, setStationContextFor]);
+    }, [filters, providers, searchQuery, setStationContextFor, store]);
+    const recallSearchHistory = useCallback((direction) => {
+        const history = store.snapshot().searchHistory;
+        if (history.length === 0) {
+            return;
+        }
+        const state = searchHistoryRef.current;
+        if (direction === 'older') {
+            if (state.cursor === -1) {
+                state.draft = searchQuery;
+            }
+            state.cursor = Math.min(history.length - 1, state.cursor + 1);
+            setSearchQuery(history[state.cursor] ?? '');
+        }
+        else if (state.cursor <= 0) {
+            state.cursor = -1;
+            setSearchQuery(state.draft);
+        }
+        else {
+            state.cursor -= 1;
+            setSearchQuery(history[state.cursor] ?? '');
+        }
+    }, [searchQuery, store]);
     const loadNearby = useCallback(async () => {
         setLoadingStations(true);
         setMessage(null);
@@ -536,6 +582,22 @@ export function App({ store: providedStore, providers: providedProviders }) {
             setMessage(message);
         }
     }, [filters, go, 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);
+    useEffect(() => {
+        if (didResumeRef.current) {
+            return;
+        }
+        didResumeRef.current = true;
+        if (!settingsRef.current.resumeOnLaunch) {
+            return;
+        }
+        const last = store.snapshot().recent[0]?.station;
+        if (last) {
+            void playStation(last);
+        }
+    }, [playStation, store]);
     playStationRef.current = playStation;
     const toggleFavorite = useCallback((station) => {
         if (!station) {
@@ -545,12 +607,40 @@ export function App({ store: providedStore, providers: providedProviders }) {
         const wasFavorite = store.isFavorite(station);
         setLibrary(store.toggleFavorite(station));
         setMessage(`${wasFavorite ? 'Removed from' : 'Added to'} favorites: ${station.name}`);
-    }, [store]);
+        if (!wasFavorite) {
+            // Best-effort upvote back to the directory; never blocks favoriting.
+            void providers.vote(station);
+        }
+    }, [providers, store]);
     const showControlResult = useCallback((result) => {
         if (!result.ok && result.message) {
             setMessage(result.message);
         }
     }, []);
+    const openStationHomepage = useCallback((station) => {
+        if (!station?.homepage) {
+            setMessage('This station has no homepage.');
+            return;
+        }
+        openExternal(station.homepage);
+        setMessage(`Opening homepage: ${station.name}`);
+    }, []);
+    const copyStationUrl = useCallback(async (station) => {
+        if (!station) {
+            setMessage('Select or play a station first.');
+            return;
+        }
+        let url = station.streamUrl;
+        if (!url) {
+            url = await providers.resolve(station).then(resolved => resolved.url).catch(() => undefined);
+        }
+        if (!url) {
+            setMessage(`No stream URL available for ${station.name}.`);
+            return;
+        }
+        const copied = copyToClipboard(url);
+        setMessage(copied ? `Copied stream URL: ${station.name}` : `Stream URL: ${url}`);
+    }, [providers]);
     const submitAirPlayCode = useCallback((code) => {
         const result = player.submitAirPlayPasscode(code);
         if (result.ok) {
@@ -695,6 +785,11 @@ export function App({ store: providedStore, providers: providedProviders }) {
         updateSettings({ skipBrokenStreams });
         setMessage(`Skip broken streams ${skipBrokenStreams ? 'enabled' : 'disabled'}.`);
     }, [updateSettings]);
+    const toggleSetting = useCallback((key) => {
+        const next = !settingsRef.current[key];
+        updateSettings({ [key]: next });
+        setMessage(`${settingToggleLabel[key]} ${next ? 'on' : 'off'}.`);
+    }, [updateSettings]);
     const cycleSleepTimer = useCallback(() => {
         const currentMinutes = sleepUntil ? Math.round((sleepUntil - Date.now()) / 60000) : null;
         const next = nextSleepTimerMinutes(currentMinutes);
@@ -798,6 +893,8 @@ export function App({ store: providedStore, providers: providedProviders }) {
         adjustVolume,
         airPlayCode,
         canEnterAirPlayCode,
+        copyStationUrl,
+        openStationHomepage,
         beginLearningTransportKey,
         capturingTransportAction,
         commandMode,
@@ -823,6 +920,7 @@ export function App({ store: providedStore, providers: providedProviders }) {
         playStation,
         player,
         playingStation,
+        recallSearchHistory,
         moveExploreCursor: moveExploreMapCursor,
         moveExploreCursorToCell: moveExploreMapCursorToCell,
         refreshProviderHealth,
@@ -855,6 +953,7 @@ export function App({ store: providedStore, providers: providedProviders }) {
         toggleFavorite,
         toggleMute,
         togglePause,
+        toggleSetting,
         toggleNearbyLocation,
         toggleRadioGarden,
         toggleSkipBrokenStreams
@@ -864,10 +963,10 @@ export function App({ store: providedStore, providers: providedProviders }) {
     }
     const hasTopTabs = !layout.compact;
     const globalFooter = playback.backend === 'ffplay'
-        ? '←/→ tabs · F7/F9 or ,/. station · ffplay fallback: limited controls · t/v display · q quit'
+        ? '←/→ tabs · F7/F9 or ,/. station · ffplay fallback: limited controls · t/v display · ? help · q quit'
         : playback.backend === 'airplay'
-            ? '←/→ tabs · F7/F9 or ,/. station · AirPlay: +/- volume, m mute · t/v display · q quit'
-            : '←/→ tabs · F7/F9 or ,/. station · F8 pause · t/v display · +/- volume · q quit';
+            ? '←/→ tabs · F7/F9 or ,/. station · AirPlay: +/- volume, m mute · t/v display · ? help · q quit'
+            : '←/→ tabs · F7/F9 or ,/. station · F8 pause · t/v display · +/- volume · ? help · q quit';
     const playbackFooter = playbackFooterText({
         station: playingStation,
         playback,
@@ -888,7 +987,7 @@ export function App({ store: providedStore, providers: providedProviders }) {
         playbackBackend: playback.backend,
         screen
     });
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, height: layout.rows, width: layout.columns, overflow: "hidden", backgroundColor: appBackground, children: [hasTopTabs ? (_jsx(Box, { height: 3, marginBottom: 1, flexShrink: 0, backgroundColor: appBackground, children: _jsx(TopTabs, { tabs: topTabs, active: activeTabForScreen(screen), theme: theme, width: frameWidth, rightLabel: `${playbackBackendLabel(playback.backend)} · ${playback.state}` }) })) : null, _jsxs(Box, { height: layout.contentRows, width: frameWidth, flexDirection: "column", overflowY: "hidden", flexShrink: 0, backgroundColor: appBackground, children: [_jsx(AppContent, { airPlayDevices: availableAirPlayDevices, airPlayCode: airPlayCode, 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: playback, playingStation: playingStation, providerHealth: providerHealth, pulse: pulse, searchQuery: searchQuery, screen: screen, selected: selected, showDiagnostics: showDiagnostics, sleepLabel: sleepLabel, stationContext: stationContext, exploreCursor: exploreCursor, stationFavorite: store.isFavorite(playingStation), stationTime: stationApproximateTime(playingStation), storePath: store.filePath, theme: theme }), message ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: themeAccent(theme), children: message }) })) : null] }), _jsxs(Box, { height: layout.footerRows, width: frameWidth, flexDirection: "column", flexShrink: 0, backgroundColor: panelBackground, children: [playbackFooter ? _jsx(Text, { color: themeAccent(theme), children: playbackFooter }) : null, _jsx(Text, { color: commandMode || capturingTransportAction ? themeAccent(theme) : 'gray', children: truncate(pageFooter, frameWidth) }), _jsx(Text, { color: textDim, children: truncate(globalFooter, frameWidth) })] })] }));
+    return (_jsx(DisplayContext.Provider, { value: displayMode, children: _jsxs(Box, { flexDirection: "column", paddingX: 1, height: layout.rows, width: layout.columns, overflow: "hidden", backgroundColor: displayMode.app, children: [hasTopTabs ? (_jsx(Box, { height: 3, marginBottom: 1, flexShrink: 0, backgroundColor: displayMode.app, children: _jsx(TopTabs, { tabs: topTabs, active: activeTabForScreen(screen), theme: theme, width: frameWidth, rightLabel: `${playbackBackendLabel(playback.backend)} · ${playback.state}` }) })) : null, _jsxs(Box, { height: layout.contentRows, width: frameWidth, flexDirection: "column", overflowY: "hidden", flexShrink: 0, backgroundColor: displayMode.app, children: [_jsx(AppContent, { airPlayDevices: availableAirPlayDevices, airPlayCode: airPlayCode, 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: playback, playingStation: playingStation, providerHealth: providerHealth, pulse: pulse, searchQuery: searchQuery, screen: screen, selected: selected, showDiagnostics: showDiagnostics, sleepLabel: sleepLabel, stationContext: stationContext, exploreCursor: exploreCursor, stationFavorite: store.isFavorite(playingStation), stationTime: stationApproximateTime(playingStation), storePath: store.filePath, theme: theme }), message ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: themeAccent(theme), children: message }) })) : null] }), _jsxs(Box, { height: layout.footerRows, width: frameWidth, flexDirection: "column", flexShrink: 0, backgroundColor: displayMode.panel, children: [playbackFooter ? _jsx(Text, { color: themeAccent(theme), children: playbackFooter }) : null, _jsx(Text, { color: commandMode || capturingTransportAction ? themeAccent(theme) : 'gray', children: truncate(pageFooter, frameWidth) }), _jsx(Text, { color: textDim, children: truncate(globalFooter, frameWidth) })] })] }) }));
 }
 function buildLibraryStations(library) {
     const stations = [];
@@ -937,7 +1036,7 @@ function formatDistanceKm(distanceKm) {
 }
 function nextAvailablePlaybackBackend(current, backends) {
     const options = ['auto'];
-    for (const backend of ['mpv', 'ffplay', 'airplay']) {
+    for (const backend of ['mpv', 'ffplay', 'vlc', 'airplay']) {
         if (backends.includes(backend)) {
             options.push(backend);
         }
@@ -962,6 +1061,9 @@ function preferredLocalPlaybackBackend(backends) {
     if (backends.includes('ffplay')) {
         return 'ffplay';
     }
+    if (backends.includes('vlc')) {
+        return 'vlc';
+    }
     return null;
 }
 function audioOutputSwitchLabel(output, backends) {

package/dist/ui/AppContent.js

@@ -10,6 +10,7 @@ import { StationScreen } from './screens/StationScreen.js';
 import { NowPlayingScreen } from './screens/NowPlayingScreen.js';
 import { StatsScreen } from './screens/StatsScreen.js';
 import { SettingsScreen } from './screens/SettingsScreen.js';
+import { HelpScreen } from './screens/HelpScreen.js';
 import { AirPlaySettingsScreen } from './screens/AirPlaySettingsScreen.js';
 import { AirPlayCodeScreen } from './screens/AirPlayCodeScreen.js';
 import { selectedAirPlayDevice } from './airplay-settings.js';
@@ -37,7 +38,7 @@ export function AppContent({ airPlayDevices, airPlayCode, backends, countryFilte
         return (_jsx(StationScreen, { title: stationContext.title, subtitle: stationContext.subtitle, stations: displayStations, selected: selected, loading: loadingStations, theme: theme, favorites: favoriteKeys, filterLabel: filterLabel, pageSize: layout.stationRows, width: frameWidth }));
     }
     if (screen === 'now-playing') {
-        return (_jsx(NowPlayingScreen, { station: playingStation, playback: playback, metadata: nowPlaying, theme: theme, favorite: stationFavorite, pulse: pulse, diagnostics: diagnostics, sleepLabel: sleepLabel, showDiagnostics: showDiagnostics, stationTime: stationTime, receiverStyle: library.settings.receiverStyle, width: layout.receiverWidth, height: layout.receiverRows }));
+        return (_jsx(NowPlayingScreen, { station: playingStation, playback: playback, metadata: nowPlaying, theme: theme, favorite: stationFavorite, pulse: pulse, diagnostics: diagnostics, sleepLabel: sleepLabel, showDiagnostics: showDiagnostics, stationTime: stationTime, receiverStyle: library.settings.receiverStyle, trackHistory: library.trackHistory, width: layout.receiverWidth, height: layout.receiverRows }));
     }
     if (screen === 'stats') {
         return _jsx(StatsScreen, { library: library, theme: theme, width: frameWidth, height: layout.contentRows });
@@ -51,5 +52,8 @@ export function AppContent({ airPlayDevices, airPlayCode, backends, countryFilte
     if (screen === 'airplay-code') {
         return (_jsx(AirPlayCodeScreen, { code: airPlayCode, playback: playback, selectedDevice: selectedAirPlayDevice(library.settings, airPlayDevices), theme: theme, width: frameWidth }));
     }
+    if (screen === 'help') {
+        return _jsx(HelpScreen, { theme: theme, width: frameWidth });
+    }
     return _jsx(Text, { children: "Unknown screen." });
 }

package/dist/ui/app-state.js

@@ -6,7 +6,7 @@ const emptyMediaKeyBindings = {
 };
 const mediaTransportActions = ['previous', 'playPause', 'next'];
 const sleepTimerOptions = [null, 15, 30, 60];
-const playbackBackendOptions = ['auto', 'mpv', 'ffplay', 'airplay'];
+const playbackBackendOptions = ['auto', 'mpv', 'ffplay', 'vlc', 'airplay'];
 export const defaultExploreCursor = {
     latitude: 48.8566,
     longitude: 2.3522

package/dist/ui/ascii.js

@@ -0,0 +1,84 @@
+// Map a single Unicode code point to a width-1 ASCII approximation. Used by the
+// ASCII-safe display mode so terminals/fonts without braille, block, or
+// box-drawing glyphs still render a legible receiver and chrome.
+const shadeRamp = ' .:-=+*#%@';
+function asciiGlyph(code) {
+    // Braille patterns: approximate by how many dots are raised (0-8).
+    if (code >= 0x2800 && code <= 0x28ff) {
+        const dots = popcount(code - 0x2800);
+        const index = Math.round((dots / 8) * (shadeRamp.length - 1));
+        return shadeRamp[index] ?? '#';
+    }
+    // Light/medium/dark shade blocks.
+    if (code === 0x2591) {
+        return '.';
+    }
+    if (code === 0x2592) {
+        return ':';
+    }
+    if (code === 0x2593) {
+        return '#';
+    }
+    // Block elements (full, partial, half blocks).
+    if (code >= 0x2580 && code <= 0x259f) {
+        return '#';
+    }
+    // Box drawing.
+    if (code >= 0x2500 && code <= 0x257f) {
+        if (code === 0x2500 || code === 0x2501 || code === 0x2504 || code === 0x2505) {
+            return '-';
+        }
+        if (code === 0x2502 || code === 0x2503 || code === 0x2506 || code === 0x2507) {
+            return '|';
+        }
+        return '+';
+    }
+    // Common standalone marks.
+    // Density-style marks: keep a low-to-high ramp so map textures stay legible.
+    if (code === 0x00b7) {
+        return '.'; // middle dot ·
+    }
+    if (code === 0x2026) {
+        return '.'; // ellipsis …
+    }
+    if (code === 0x2022) {
+        return 'o'; // bullet •
+    }
+    if (code === 0x25cf) {
+        return '@'; // black circle ●
+    }
+    if (code === 0x25cb || code === 0x25aa || code === 0x25a0) {
+        return '*';
+    }
+    if (code === 0x2605) {
+        return '*'; // ★
+    }
+    if (code === 0x2606) {
+        return 'o'; // ☆
+    }
+    if (code === 0x2014 || code === 0x2013) {
+        return '-';
+    }
+    // Drop zero-width and combining marks entirely so they do not skew widths.
+    if (code === 0x200b || code === 0xfeff || (code >= 0x0300 && code <= 0x036f)) {
+        return '';
+    }
+    return '*';
+}
+function popcount(value) {
+    let count = 0;
+    let remaining = value;
+    while (remaining > 0) {
+        count += remaining & 1;
+        remaining >>>= 1;
+    }
+    return count;
+}
+export function toAsciiSafe(value) {
+    let out = '';
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        out += code < 0x80 ? char : asciiGlyph(code);
+    }
+    return out;
+}

package/dist/ui/audio-output.js

@@ -9,6 +9,9 @@ export function audioOutputLabel(output) {
     if (output === 'ffplay') {
         return 'This device (ffplay fallback)';
     }
+    if (output === 'vlc') {
+        return 'This device (VLC fallback)';
+    }
     if (output === 'airplay') {
         return 'AirPlay';
     }
@@ -21,7 +24,7 @@ export function resolvedAudioOutput(output, backends) {
     if (output !== 'auto') {
         return backends.includes(output) ? output : null;
     }
-    for (const backend of ['mpv', 'ffplay']) {
+    for (const backend of ['mpv', 'ffplay', 'vlc']) {
         if (backends.includes(backend)) {
             return backend;
         }

package/dist/ui/components/ScreenHeader.js

@@ -1,15 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { textDim, themeAccent } from '../theme.js';
+import { useDisplay } from '../display-context.js';
+import { toAsciiSafe } from '../ascii.js';
 import { truncate } from '../format.js';
 // One title treatment shared by every screen: an accented, bold title trailed by
 // a dim rule that fills the frame, with optional right-aligned meta and a muted
 // subtitle below. Renders one row (plus one for the subtitle when present).
 export function ScreenHeader({ title, width, theme, subtitle, right }) {
     const accent = themeAccent(theme);
+    const { ascii } = useDisplay();
+    const a = (value) => (ascii ? toAsciiSafe(value) : value);
     const safeTitle = truncate(title, Math.max(4, width - 4));
     const rightText = right ? ` ${right}` : '';
     const ruleWidth = Math.max(1, width - safeTitle.length - rightText.length - 2);
-    const rule = '─'.repeat(ruleWidth);
-    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsxs(Box, { children: [_jsx(Text, { color: accent, bold: true, children: safeTitle }), _jsxs(Text, { color: textDim, children: [" ", rule] }), rightText ? _jsx(Text, { color: "gray", children: rightText }) : null] }), subtitle ? _jsx(Text, { color: "gray", children: truncate(subtitle, width) }) : null] }));
+    const rule = (ascii ? '-' : '─').repeat(ruleWidth);
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsxs(Box, { children: [_jsx(Text, { color: accent, bold: true, children: a(safeTitle) }), _jsxs(Text, { color: textDim, children: [" ", rule] }), rightText ? _jsx(Text, { color: "gray", children: a(rightText) }) : null] }), subtitle ? _jsx(Text, { color: "gray", children: a(truncate(subtitle, width)) }) : null] }));
 }

package/dist/ui/components/TopTabs.js

@@ -1,9 +1,14 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
-import { panelBackground, panelBorder, themeAccent } from '../theme.js';
+import { panelBorder, themeAccent } from '../theme.js';
+import { useDisplay } from '../display-context.js';
 import { truncate } from '../format.js';
 export function TopTabs({ tabs, active, theme, width, rightLabel }) {
     const accent = themeAccent(theme);
+    const { panel: panelBackground, ascii } = useDisplay();
+    const box = ascii
+        ? { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|' }
+        : { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│' };
     const brand = 'RADIOCLI';
     const rightText = ` ${rightLabel} `;
     const bodyWidth = Math.max(1, width - 4);
@@ -15,7 +20,7 @@ export function TopTabs({ tabs, active, theme, width, rightLabel }) {
     const visibleTabs = fitTabs(tabs, active, tabsAvailableWidth);
     const visibleTabsWidth = tabsWidth(visibleTabs);
     const tabPaddingWidth = Math.max(0, bodyWidth - visibleTabsWidth - (canShowRight ? rightText.length : 0));
-    return (_jsxs(Box, { flexDirection: "column", backgroundColor: panelBackground, width: width, children: [_jsxs(Text, { backgroundColor: panelBackground, children: [_jsx(Text, { color: panelBorder, children: "\u250C " }), _jsx(Text, { color: accent, bold: true, children: brand }), _jsxs(Text, { color: panelBorder, children: [" ", '─'.repeat(titleRuleWidth), "\u2510"] })] }), _jsxs(Text, { backgroundColor: panelBackground, children: [_jsx(Text, { color: panelBorder, children: "\u2502 " }), visibleTabs.map((item, index) => (_jsxs(Text, { children: [item.type === 'overflow' ? (_jsx(Text, { color: "gray", children: "\u2026" })) : (_jsx(Text, { color: item.tab.screen === active ? accent : 'gray', bold: item.tab.screen === active, children: item.tab.label })), index < visibleTabs.length - 1 ? _jsx(Text, { color: "gray", children: " \u2502 " }) : null] }, item.type === 'overflow' ? `${item.side}-overflow` : item.tab.screen))), _jsx(Text, { children: ' '.repeat(tabPaddingWidth) }), canShowRight ? _jsx(Text, { color: "gray", children: rightText }) : null, _jsx(Text, { color: panelBorder, children: " \u2502" })] }), _jsxs(Text, { backgroundColor: panelBackground, color: panelBorder, children: ["\u2514", '─'.repeat(Math.max(0, width - 2)), "\u2518"] })] }));
+    return (_jsxs(Box, { flexDirection: "column", backgroundColor: panelBackground, width: width, children: [_jsxs(Text, { backgroundColor: panelBackground, children: [_jsxs(Text, { color: panelBorder, children: [box.tl, " "] }), _jsx(Text, { color: accent, bold: true, children: brand }), _jsxs(Text, { color: panelBorder, children: [" ", box.h.repeat(titleRuleWidth), box.tr] })] }), _jsxs(Text, { backgroundColor: panelBackground, children: [_jsxs(Text, { color: panelBorder, children: [box.v, " "] }), visibleTabs.map((item, index) => (_jsxs(Text, { children: [item.type === 'overflow' ? (_jsx(Text, { color: "gray", children: "\u2026" })) : (_jsx(Text, { color: item.tab.screen === active ? accent : 'gray', bold: item.tab.screen === active, children: item.tab.label })), index < visibleTabs.length - 1 ? _jsxs(Text, { color: "gray", children: [" ", box.v, " "] }) : null] }, item.type === 'overflow' ? `${item.side}-overflow` : item.tab.screen))), _jsx(Text, { children: ' '.repeat(tabPaddingWidth) }), canShowRight ? _jsx(Text, { color: "gray", children: rightText }) : null, _jsxs(Text, { color: panelBorder, children: [" ", box.v] })] }), _jsxs(Text, { backgroundColor: panelBackground, color: panelBorder, children: [box.bl, box.h.repeat(Math.max(0, width - 2)), box.br] })] }));
 }
 function fitTabs(tabs, active, maxWidth) {
     const all = tabs.map(tab => ({ type: 'tab', tab }));

package/dist/ui/display-context.js

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+import { appBackground, panelBackground } from './theme.js';
+const opaqueBackgrounds = { app: appBackground, panel: panelBackground };
+const transparentBackgrounds = { app: undefined, panel: undefined };
+// Respect the NO_COLOR convention (https://no-color.org): any non-empty value
+// opts the user out of our forced colors, including the dark panel fills.
+export function noColorRequested(env = process.env) {
+    return typeof env.NO_COLOR === 'string' && env.NO_COLOR.length > 0;
+}
+// Resolve the effective display mode from the user's settings and the NO_COLOR
+// environment so light terminals keep their own background.
+export function resolveDisplayMode(settings, env = process.env) {
+    const backgrounds = settings.transparentBackground || noColorRequested(env) ? transparentBackgrounds : opaqueBackgrounds;
+    return { ...backgrounds, ascii: Boolean(settings.asciiMode), reduceMotion: Boolean(settings.reduceMotion) };
+}
+const defaultMode = { ...opaqueBackgrounds, ascii: false, reduceMotion: false };
+export const DisplayContext = createContext(defaultMode);
+export function useDisplay() {
+    return useContext(DisplayContext);
+}
+// Ink's rounded/single borders are Unicode box-drawing; "classic" is ASCII
+// (+-|) and renders on terminals and fonts without box-drawing glyphs.
+export function panelBorderStyle(ascii, base = 'round') {
+    return ascii ? 'classic' : base;
+}

package/dist/ui/help-content.js

@@ -0,0 +1,116 @@
+export const keyHelpSections = [
+    {
+        title: 'Navigation',
+        entries: [
+            { keys: '↑/↓ or n/p', description: 'Move selection' },
+            { keys: '←/→ or Tab', description: 'Switch tabs' },
+            { keys: '[ / ]', description: 'Page selection by 10' },
+            { keys: '1-9, 0', description: 'Jump to home menu item' },
+            { keys: 'Enter', description: 'Open / tune the selection' },
+            { keys: 'b or Esc', description: 'Back to home' },
+            { keys: ': ', description: 'Command palette' },
+            { keys: '?', description: 'Toggle this help' },
+            { keys: 'q or Ctrl+C', description: 'Quit' }
+        ]
+    },
+    {
+        title: 'Playback',
+        entries: [
+            { keys: 'space or F8', description: 'Pause / resume' },
+            { keys: ', / . or F7/F9', description: 'Previous / next station' },
+            { keys: '+ / -', description: 'Volume up / down' },
+            { keys: 'm', description: 'Mute / unmute' },
+            { keys: 'f', description: 'Favorite the station' },
+            { keys: 'O', description: 'Open station homepage' },
+            { keys: 'y', description: 'Copy stream URL' },
+            { keys: 's', description: 'Sleep timer (Now Playing)' },
+            { keys: 'd', description: 'Diagnostics + recent tracks (Now Playing)' }
+        ]
+    },
+    {
+        title: 'Display & discovery',
+        entries: [
+            { keys: 't', description: 'Cycle display color' },
+            { keys: 'v', description: 'Cycle receiver style' },
+            { keys: 'o', description: 'Cycle audio output' },
+            { keys: '/', description: 'Edit search / country filter' },
+            { keys: 'w', description: 'Toggle country list / world map' },
+            { keys: 'WASD', description: 'Move the Explore map cursor' },
+            { keys: 'r', description: 'Refresh provider health' }
+        ]
+    }
+];
+export const commandHelp = [
+    { name: 'search', args: '<query>', description: 'Search stations (alias :s)' },
+    { name: 'country', args: '<name|code>', description: 'Open a country (alias :c)' },
+    { name: 'codec', args: '<codec|any>', description: 'Filter by codec' },
+    { name: 'language', args: '<lang|any>', description: 'Filter by language (alias :lang)' },
+    { name: 'bitrate', args: '<kbps>', description: 'Minimum bitrate filter' },
+    { name: 'clear', description: 'Clear search filters' },
+    { name: 'volume', args: '<0-100>', description: 'Set volume (alias :vol)' },
+    { name: 'mute', description: 'Toggle mute' },
+    { name: 'sleep', args: '<minutes>', description: 'Set or clear the sleep timer' },
+    { name: 'timeout', args: '<seconds>', description: 'Tune timeout (3-45)' },
+    { name: 'skip', args: '<on|off>', description: 'Skip broken streams' },
+    { name: 'location', args: '<on|off>', description: 'Nearby location lookup' },
+    { name: 'doctor', description: 'Show playback backend status' },
+    { name: 'resume', args: '<on|off>', description: 'Resume last station on launch' },
+    { name: 'ascii', args: '<on|off>', description: 'ASCII-safe display' },
+    { name: 'motion', args: '<on|off>', description: 'Reduce motion' },
+    { name: 'background', args: '<on|off>', description: 'Transparent background' },
+    { name: 'airplay', description: 'Open AirPlay settings' },
+    { name: 'learn', args: '<previous|play|next>', description: 'Learn a media key' },
+    { name: 'keys', args: '[reset]', description: 'Show or reset learned media keys' },
+    { name: 'favorite', description: 'Favorite the current station (alias :fav)' },
+    { name: 'library', description: 'Open the library' },
+    { name: 'map', description: 'Open the world map' },
+    { name: 'stats', description: 'Open listening stats' },
+    { name: 'settings', description: 'Open settings' },
+    { name: 'stop', description: 'Stop playback' },
+    { name: 'help', description: 'Open this help' }
+];
+// Primary command names plus the aliases the executor accepts, used for
+// command-mode tab completion.
+export const commandNames = [
+    's',
+    'c',
+    'lang',
+    'vol',
+    'fav',
+    'recent',
+    'favorites',
+    'imports',
+    'bind',
+    'key',
+    'airplay-code',
+    'airplay-settings',
+    ...commandHelp.map(entry => entry.name)
+].sort((a, b) => a.localeCompare(b));
+// Complete a partial command name to the longest shared prefix of its matches.
+// Returns the original value when there is no match.
+export function completeCommand(partial, names = commandNames) {
+    const lower = partial.toLowerCase();
+    const matches = names.filter(name => name.startsWith(lower));
+    if (matches.length === 0) {
+        return partial;
+    }
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    return longestCommonPrefix(matches) || partial;
+}
+function longestCommonPrefix(values) {
+    if (values.length === 0) {
+        return '';
+    }
+    let prefix = values[0];
+    for (const value of values.slice(1)) {
+        while (!value.startsWith(prefix)) {
+            prefix = prefix.slice(0, -1);
+            if (!prefix) {
+                return '';
+            }
+        }
+    }
+    return prefix;
+}

package/dist/ui/page-footer.js

@@ -10,7 +10,7 @@ export function pageFooterText({ capturingTransportAction, commandMode, commandT
         return '↑/↓ move · Enter open · number jump · : command';
     }
     if (screen === 'search' && editingSearch) {
-        return 'Type query · Backspace edit · Enter search/tune · Esc finish';
+        return 'Type query · ↑/↓ history · Enter search/tune · Esc finish';
     }
     if (screen === 'search') {
         return '/ edit query · ↑/↓ or n/p move · Enter tune · f favorite · b home';
@@ -55,5 +55,8 @@ export function pageFooterText({ capturingTransportAction, commandMode, commandT
     if (screen === 'stats') {
         return 'b home';
     }
+    if (screen === 'help') {
+        return '? or b close · : command';
+    }
     return ': command';
 }