@ciphore/radiocli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to RadioCLI are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-30
+
+Initial public release.
+
+### Added
+
+- A square braille spinner now animates to the left of the station name in the
+  live playback footer while a station is buffering.
+- Ink-based terminal UI with overview, now playing, library, explore, search,
+  countries, world map, nearby, stats, and settings screens.
+- Radio Browser provider with mirror fallback, durable cache, and tune
+  resolution, plus an experimental, opt-in Radio Garden provider.
+- `mpv` playback with `ffplay` fallback, readiness checks, ICY metadata polling,
+  volume, pause, mute, sleep timer, tune timeouts, and skip-broken-stream
+  behavior.
+- Receiver-style Now Playing screen with 50 selectable visualizers and
+  zero-signal frames whenever playback is idle, paused, stopped, or not
+  backend-ready.
+- Explore map: a braille world map beside the live station list with WASD
+  movement, click-to-place mouse support, and a cached geotagged station atlas
+  ranked by distance.
+- Local-first library: recents, favorites, imports, listening activity,
+  settings, learned media keys, and provider cache stored as JSON on your
+  machine.
+- Playlist import/export for `.m3u`, `.pls`, and `.xspf`.
+- Listening stats with a 52-week local-calendar contribution graph, sessions,
+  streaks, active days, and total hours listened.
+- `radiocli doctor` to report local playback readiness and print OS-specific
+  setup guidance.
+- Homebrew formula template for `brew install` distribution.
+
+### Changed
+
+- Tightened the Now Playing panel below the receiver: collapsed the stream
+  tech/tags, track metadata, and backend/volume rows into two compact lines
+  (track + favorite, then a single tech · tags · sleep line), dropping
+  backend/volume that already appear in the header and footer. The reclaimed
+  rows go to the visualizer.
+
+[0.1.0]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of Conduct
+
+RadioCLI follows the Contributor Covenant standard in spirit: be respectful,
+constructive, and precise. This project welcomes users and contributors who care
+about terminal software, radio, resilient public APIs, and thoughtful product
+craft.
+
+Unacceptable behavior includes harassment, personal attacks, deliberate
+disruption, doxxing, or dismissive conduct toward people reporting issues in
+good faith.
+
+Project maintainers may remove comments, close issues, or block participants
+when behavior makes the project less useful or less welcoming.

package/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thanks for considering a contribution. RadioCLI is intentionally small, but
+the bar is high: changes should improve the product, preserve terminal
+ergonomics, and respect the unreliability of public radio streams.
+
+## Setup
+
+```bash
+npm ci
+npm run build
+npm run test
+```
+
+Install `mpv` for the best playback experience:
+
+```bash
+brew install mpv
+```
+
+On Linux, use your package manager's `mpv` package.
+
+## Verification
+
+Run these before opening a PR:
+
+```bash
+npm run check
+npm run lint
+npm run test
+npm run build
+```
+
+Run `npm run smoke:playback` when changing playback code. It opens a public
+stream briefly, so do not run it in environments where audio/network access is
+not acceptable.
+
+Live provider checks are useful before releases, but ordinary pull requests
+should stay deterministic. Run `npm run verify:release` for a full maintainer
+pre-release pass that includes live data, playback, packaging, and fresh-install
+checks.
+
+## Development Principles
+
+- Keep public provider adapters isolated.
+- Treat station streams as unreliable.
+- Never make location lookup implicit.
+- Prefer clear terminal text over decorative filler.
+- Keep command-line and TUI behavior aligned.
+- Add tests for parsing, storage, layout, or provider transformations when the
+  behavior can be checked without live audio.
+
+## Issue Triage
+
+Playback issues should include station name, country, backend, and
+`radiocli check` output when possible.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ciphore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,364 @@
+# RadioCLI
+
+[![CI](https://github.com/Ciphore/RadioCLI/actions/workflows/ci.yml/badge.svg)](https://github.com/Ciphore/RadioCLI/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+
+RadioCLI is a terminal-first world radio receiver for exploring live public stations, tuning real streams, and keeping your listening history close to the command line.
+
+It is built with [Ink](https://github.com/vadimdemedes/ink), [React](https://react.dev/), [Radio Browser](https://api.radio-browser.info/), and `mpv`. The goal is not a thin wrapper around a station list. The goal is a polished TUI product: fast discovery, resilient stream handling, local-first library state, and the kind of engineering surface that can grow without turning into terminal spaghetti.
+
+## Features
+
+- Explore public radio from around the world through a cosmo-style braille world map beside the station list, with click-to-place mouse support and WASD keyboard movement backed by a cached geotagged station atlas. Country lists, global station search, a country-density map, and opt-in nearby discovery round out the discovery surface.
+- Tune stations with `mpv` first and `ffplay` fallback when available.
+- Use a receiver-style Now Playing screen with 50 selectable receiver visualizers, backend status, cleaned ICY track metadata, stream diagnostics, sleep timer, favorite state, volume, pause, mute, station skipping, and zero-signal graphics whenever playback is idle, paused, stopped, or not backend-ready.
+- Keep shortcuts in a fixed adaptive footer: a compact live station and track row appears above page-specific and global controls while playback is active.
+- Move previous/next through the exact station list you tuned from, even after navigating to another screen.
+- Browse dense station lists with inline location/codec metadata and yellow favorite stars next to station names.
+- Search by station name, place, language, tag, codec, or minimum bitrate.
+- Keep local recents, favorites, imported stations, listening activity, playback settings, learned media keys, and provider cache.
+- Review listening stats with a GitHub-style local-calendar contribution graph, favorite station, thresholded stations listened, sessions, streaks, active days, and total hours listened from persisted sessions.
+- Import `.m3u`, `.pls`, and `.xspf` playlists, including nested local playlists.
+- Export favorites and imports as `.m3u`.
+- Survive ordinary internet-radio failure modes with provider mirror fallback, stale cache fallback, corrupt-file backups, tune timeouts, and skip-broken-stream behavior.
+- Resize with the terminal. The app listens for terminal resize events and recomputes list row counts, map density, receiver width, and compact-mode fallback from the current dimensions.
+
+## Demo
+
+The interactive TUI opens directly into the product, not a marketing screen:
+
+```text
+┌ RADIOCLI ──────────────────────────────────────────────────────────┐
+│ Overview │ Playing │ Library │ Explore │ Search │ Countries │ … │ idle │
+└──────────────────────────────────────────────────────────────────────┘
+RADIOCLI  ██████████████████
+Live public radio from around the world
+
+> 1 Playing · Receiver display and controls
+  2 Library · Favorites, recent stations, imported streams
+  3 Explore · Move a map cursor through geotagged stations
+  4 Search · Find stations by name, genre, language, place
+  5 Countries · Browse by country list with a world-map toggle
+  6 Nearby · Opt-in approximate location for local stations
+  7 Stats · Listening graph, sessions, streaks, hours
+  8 Settings · Playback backend, colors, providers
+
+3 recent · 2 favorites · 1 imported
+
+↑/↓ move · Enter open · number jump · : command
+←/→ tabs · F7/F9 or ,/. station · F8 pause · t/v display · +/- volume · q quit
+```
+
+The Now Playing screen is a framed receiver panel with **50 selectable receiver styles**. The sample below shows the default pulse-grid display; press `v` to cycle through the catalog, which spans several families:
+
+- **Classic receiver** — equalizer, LEDs, and goniometer.
+- **High-resolution braille** — smooth waveform, radial EQ, spectrogram, nebula, silk, ripple tank, phyllotaxis, harmonograph, bloom bars, moiré, galaxy, caustics.
+- **Generative & motion** — matrix, hologram, spinning ASCII cube, generated fire, fireworks, plasma, spinning donut, starfield, Lorenz attractor, Barnsley fern, Chladni plate, rotating tesseract, torus knot, fractal tree, Julia sets, and lava-lamp motion.
+
+Visualizers animate only while playback is actually playing and backend-ready; paused, stopped, idle, loading, and error states render a flat zero-signal display instead of a frozen waveform:
+
+```text
+Now playing ──────────────────────────────────────────────── mpv · playing
+╭────────────────────────────────────────────────────────────────────────╮
+│ FM 128.M      RADIOCLI                                           PLAYING │
+│ KEXP 90.3 FM                                                            │
+│ UNITED STATES · WASHINGTON                                              │
+│      ▌       ▌     ▌       ▌       ▌       ▌       ▌       ▌           │
+│  ▌   ▌   ▌   ▌ ▌   ▌   ▌   ▌   ▌   ▌   ▌   ▌   ▌   ▌   ▌   ▌           │
+│  ▌ ▌ ▌   ▌ ▌ ▌ ▌ ▌ ▌   ▌ ▌ ▌   ▌ ▌ ▌   ▌ ▌ ▌   ▌ ▌ ▌   ▌ ▌ ▌           │
+│  ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌           │
+│  ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌           │
+│  ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌ ▌           │
+│ MP3 · 128 kbps · english                                                │
+│ alternative, indie, seattle                                             │
+│ Waiting for ICY track metadata                                          │
+│ Backend mpv · Vol 70       ☆ Add favorite (f)             Sleep off     │
+╰────────────────────────────────────────────────────────────────────────╯
+
+Playing: KEXP 90.3 FM · Now: Artist - Track · Seattle, Washington, United States · MP3 / 128 kbps / english · mpv · playing · vol 70 · Nearby 4/90
+space/F8 pause · f favorite · m mute · s sleep · d diagnostics · b home
+←/→ tabs · F7/F9 or ,/. station · F8 pause · t/v display · +/- volume · q quit
+```
+
+For the exact non-interactive demo transcript:
+
+```bash
+npm run demo:script
+```
+
+Recording instructions live in [the demo guide](apps/docs/content/docs/demo.mdx).
+
+## Documentation Website
+
+The public website and the manual now live together in `apps/docs`, a Fumadocs-powered Next app. It renders the homepage at `/`, the documentation tree at `/docs`, docs search at `/api/search`, generated page images, and LLM-readable text routes.
+
+Docs content is written as MDX in `apps/docs/content/docs`, with the navigation tree defined by the local `meta.json` files.
+
+Useful commands from the repo root:
+
+```bash
+npm run docs:dev
+npm run docs:check
+npm run docs:build
+```
+
+Set `NEXT_PUBLIC_SITE_URL` for the canonical public docs URL. Preview builds also read Vercel's `VERCEL_URL` and Cloudflare Pages' `CF_PAGES_URL`.
+
+## Install
+
+Requirements:
+
+- Node.js 22 or newer
+- `mpv` for best playback; RadioCLI expects one local playback backend at runtime
+- `ffplay` from FFmpeg as an optional fallback
+
+NPM installs RadioCLI and its JavaScript dependencies. It does not install native
+system playback tools. Use `radiocli doctor` after installation to check local
+playback readiness and get the right setup command for your OS:
+
+```bash
+npm install -g @ciphore/radiocli
+radiocli doctor
+radiocli
+```
+
+macOS with npm:
+
+```bash
+brew install mpv
+npm install -g @ciphore/radiocli
+radiocli
+```
+
+Linux with npm:
+
+```bash
+sudo apt install mpv
+npm install -g @ciphore/radiocli
+radiocli
+```
+
+`ffplay` is optional fallback support. Install FFmpeg separately if you want it:
+
+```bash
+brew install ffmpeg        # macOS
+sudo apt install ffmpeg    # Debian/Ubuntu
+```
+
+The repo also includes a Homebrew formula template in `packaging/homebrew` for a
+native one-command macOS tap. Once the tap formula is published, the intended
+Homebrew install path is:
+
+```bash
+brew install ciphore/tap/radiocli
+```
+
+That formula depends on `node` and `mpv`, keeping native dependencies in the
+native package manager instead of running system installs from npm.
+
+CI covers command-mode typecheck, tests, builds, and package checks on Ubuntu. Native Windows terminals are not release-tested yet; use WSL with Linux `mpv` / `ffplay` for the supported path.
+
+Local checkout:
+
+```bash
+git clone https://github.com/Ciphore/RadioCLI.git
+cd RadioCLI
+npm ci
+npm run build
+npm link
+radiocli
+```
+
+If you do not want to link the package globally:
+
+```bash
+npm run dev
+```
+
+## CLI Usage
+
+```bash
+radiocli                 # Start the TUI
+radiocli check           # Show local store path, playback backends, provider health
+radiocli doctor          # Show playback setup status and install guidance
+radiocli countries       # Print top countries by station count
+radiocli search "japan hits"
+radiocli import stations.m3u
+radiocli export favorites.m3u
+radiocli add-url <stream-url> [station name]
+```
+
+`radiocli export` writes `radiocli-favorites.m3u` when no output path is provided.
+
+After a local build, the same commands can be run with:
+
+```bash
+node dist/cli.js check
+node dist/cli.js search "lagos talk"
+```
+
+## TUI Controls
+
+RadioCLI keeps shortcuts at the bottom of the terminal. When playback is active, a compact live row sits above the shortcuts with station, cleaned track metadata, volume or mute state, and an active sleep timer. The page shortcut row changes with the current screen, and the global transport row stays global:
+
+- `←` / `→` or `Tab` / `Shift+Tab`: move across the top screen tabs.
+- `F7` / `F9`, `,` / `.`, or `Shift+←` / `Shift+→`: tune previous or next station from the source list, wherever you are in the TUI.
+- `space` / `F8`: pause or resume.
+- `t`: cycle display color.
+- `v`: cycle receiver style.
+- `+` / `-`: volume.
+- `q` or `Ctrl+C`: quit cleanly.
+
+Page-specific footer controls:
+
+| Screen | Controls |
+| --- | --- |
+| Home | `↑` / `↓` move, `Enter` open, number jump, `:` command |
+| Search input | type query, `Backspace` edit, `Enter` search or tune, `Esc` finish |
+| Search results | `/` edit query, `↑` / `↓` or `n` / `p` move, `Enter` tune, `f` favorite, `b` home |
+| Explore | click map, `WASD` fine move, `Shift+WASD` jump, `↑` / `↓` station, `Enter` tune, `f` favorite, `[` / `]` page, `b` home |
+| Countries | `/` filter, `↑` / `↓` move, `Enter` open stations, `w` map, `b` home |
+| World map | `/` filter, `↑` / `↓` move, `Enter` open country, `w` list, `b` home |
+| Station lists | `↑` / `↓` or `n` / `p` move, `Enter` tune, `f` favorite, `[` / `]` page, `b` home |
+| Now Playing | `space` / `F8` pause, `f` favorite, `m` mute, `s` sleep, `d` diagnostics, `b` home |
+| Settings | `Enter` change selected, `g` Radio Garden, `l` location, `x` skip broken streams, `o` backend, `r` health, `b` home |
+| Stats | `b` home |
+
+Other active shortcuts:
+
+- `Enter`: open the selected item or tune the selected station without leaving the current list.
+- `:`: command palette.
+- `/`: edit search or country filter on screens that support it.
+- `[` / `]`: page through long station and country lists.
+- `m`: mute.
+- `o`: cycle playback backend.
+- `g`: toggle the experimental Radio Garden adapter.
+- `l`: toggle nearby location lookup.
+- `x`: toggle skip-broken-stream behavior.
+- `r`: refresh provider health.
+- `f`: favorite the current or selected station.
+- `n` / `p`: move selection; on Now Playing, tune next or previous station from the source list.
+- `s`: cycle the sleep timer on Now Playing through off, 15 minutes, 30 minutes, 60 minutes, then off again.
+- `d`: stream diagnostics on Now Playing.
+- `b`: back home.
+
+When you tune a station from Library, Explore, Search, Countries, or Nearby, that list becomes the playback queue. Previous/next keeps moving through that source list from any screen until you tune from another list.
+
+Hardware media keys depend on the OS and terminal. RadioCLI maximizes compatibility by enabling enhanced keyboard reporting where supported, recognizing common F7/F8/F9 sequences, Kitty consumer/media-key codes, modified-arrow sequences, comma/dot transport fallback, and learned custom bindings. Learn keys from Settings or with `:learn previous`, `:learn play`, and `:learn next`; clear them with `:keys reset`.
+
+Explore mouse clicks use terminal mouse reporting while the Explore tab is active. If your terminal or tmux setup does not pass those events through, the WASD cursor controls stay fully available.
+
+Useful command palette entries:
+
+```text
+:search lagos jazz
+:country japan
+:codec MP3
+:language spanish
+:bitrate 128
+:clear
+:volume 60
+:mute
+:favorite
+:sleep 15
+:sleep off
+:timeout 15
+:skip off
+:location on
+:learn previous
+:learn play
+:learn next
+:keys reset
+:map
+:library
+:stats
+:settings
+:stop
+```
+
+Settings persist display colors and receiver styles without editing config files. The fourteen display colors are green, amber, blue, ruby, ice, teal, violet, copper, cyan, lime, coral, rose, slate, and mono, cycled with `t`. The 50 receiver styles span classic receiver displays, high-resolution braille visuals, and generative motion scenes; cycle them with `v` (see the [Demo](#demo) for the full family breakdown). The stats graph and legend follow the selected display color, and the selected Now Playing style is restored on the next launch.
+
+## Architecture
+
+RadioCLI is split around four seams:
+
+- TUI state and screens in `src/ui`
+- provider adapters in `src/providers`
+- playback lifecycle and metadata in `src/player`
+- local JSON persistence in `src/storage`
+
+Radio Browser is the primary provider. Its own docs recommend using a speaking user agent, resolving station clicks through `/json/url`, and retrying with other servers when one fails; RadioCLI follows that shape with mirror fallback and durable cache. Explore and Nearby use a cached geotagged Radio Browser atlas, then compute local distance in the app so map movement is not biased toward the most-clicked stations worldwide. Radio Garden support is experimental because the useful endpoints are publicly discoverable but unofficial, and they can be blocked or changed independently of this project.
+
+Playback prefers `mpv` because it handles real-world streams, redirects, HLS, codecs, and metadata better than a hand-rolled stream client. RadioCLI controls `mpv` through JSON IPC for readiness, pause, mute, volume, and metadata polling.
+
+The npm package is `@ciphore/radiocli`, and the installed executable is `radiocli`. Current installs store data under RadioCLI paths such as `radiocli.json` and `radiocli-cache.json`. Existing Radio Atlas data is still discovered when a new RadioCLI store does not exist, and legacy `RADIO_ATLAS_HOME` / animation environment variables remain supported as migration fallbacks. New automation should use `RADIOCLI_HOME` and `RADIOCLI_DISABLE_ANIMATION`.
+
+Read more:
+
+- [Architecture](apps/docs/content/docs/architecture.mdx)
+- [Design notes](apps/docs/content/docs/design.mdx)
+- [Reliability](apps/docs/content/docs/reliability.mdx)
+- [Roadmap](apps/docs/content/docs/roadmap.mdx)
+- [Release packaging](apps/docs/content/docs/release-packaging.mdx)
+
+These also render as a browsable site — run `npm run docs:dev` (see `apps/docs`).
+
+## Engineering Highlights
+
+This repo is intentionally small, but it is built like production software:
+
+- provider boundary instead of UI-coupled fetch calls
+- cached geotagged station atlas for true distance-first Explore and Nearby results
+- Zod schemas at public API and persistence boundaries
+- stale-cache fallback for directory outages
+- corrupt store/cache backup instead of silent overwrite
+- `mpv` readiness checks before reporting playback as active
+- tune timeout and skip-broken-stream behavior
+- cleaned ICY metadata, including key/value payloads such as `title="..." artist="..."` and station-specific `text="..."` fields
+- source-list playback queues for previous/next transport
+- enhanced terminal keyboard parsing with learned media-key bindings
+- local-calendar activity bucketing for late-night listening sessions
+- local-first privacy posture for history, favorites, imports, and settings
+- responsive terminal layout utility with an adaptive footer and focused tests
+- smoke tests that exercise live provider data and real playback
+- package smoke test that packs the npm artifact, installs it into a fresh temp project, and runs the installed binary
+
+## Privacy
+
+Nearby station discovery is off by default. If you enable it, RadioCLI requests approximate IP-based location from `ipapi.co` and uses the returned city/region/country/coordinates to sort the local geotagged station atlas. Explore uses only the cursor coordinate you move in the terminal. The app does not require an account, does not store secrets, and does not proxy audio. It stores recents, favorites, imports, settings, and provider cache data locally on your machine.
+
+## Development
+
+```bash
+npm ci
+npm run check
+npm run lint
+npm run test
+npm run build
+npm run docs:check
+npm run docs:build
+npm run smoke:data
+npm run verify
+npm run smoke:playback
+npm run pack:check
+npm run fresh:check
+npm run verify:release
+```
+
+`npm run smoke:playback` briefly opens a public stream through your local playback backend.
+
+## Contributing
+
+Contributions are welcome when they keep the app practical, reliable, and honest about public radio streams. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and include `radiocli check` output for playback issues.
+
+## References
+
+- [Ink README](https://github.com/vadimdemedes/ink)
+- [Radio Browser API docs](https://api.radio-browser.info/)
+- [mpv JSON IPC manual](https://mpv.io/manual/stable/#json-ipc)
+- [Unofficial Radio Garden OpenAPI notes](https://github.com/jonasrmichel/radio-garden-openapi)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security
+
+RadioCLI does not require secrets or accounts.
+
+## Reporting
+
+Open a private security advisory on GitHub:
+
+```text
+https://github.com/Ciphore/RadioCLI/security/advisories
+```
+
+If private reporting is unavailable, open a minimal public issue asking for a
+private disclosure path, but do not include exploit details. Please avoid filing
+public issues for vulnerabilities that could expose local files, private network
+information, or unexpected command execution.
+
+## Privacy Notes
+
+- Nearby station discovery is opt-in.
+- Location lookup uses approximate IP-based location from `ipapi.co` when
+  enabled.
+- The app stores recents, favorites, settings, imports, and provider cache data
+  locally under the user data directory.
+- RadioCLI does not proxy audio. It resolves public stream URLs and hands
+  playback to `mpv` or `ffplay`.
+
+## Supported Versions
+
+Until a tagged release cadence is established, security fixes target the active
+development branch and the latest public npm release.

package/dist/activity/stats.js

@@ -0,0 +1,122 @@
+import { stationKey } from '../storage/store.js';
+const trackedDays = 371;
+const listenedStationThresholdSeconds = 120;
+export function computeListeningStats(sessions, now = new Date()) {
+    const today = startOfLocalDay(now);
+    const firstDay = addLocalDays(today, -(trackedDays - 1));
+    const lastDayEnd = addLocalDays(today, 1);
+    const secondsByDay = new Map();
+    const secondsByStation = new Map();
+    let totalSeconds = 0;
+    for (const session of sessions) {
+        const seconds = sessionSeconds(session, now);
+        if (seconds <= 0) {
+            continue;
+        }
+        totalSeconds += seconds;
+        for (const allocation of splitSessionByDay(session, seconds, firstDay, lastDayEnd, now)) {
+            secondsByDay.set(allocation.date, (secondsByDay.get(allocation.date) ?? 0) + allocation.seconds);
+        }
+        const key = stationKey(session.station);
+        const current = secondsByStation.get(key) ?? { station: session.station, seconds: 0 };
+        secondsByStation.set(key, { station: current.station, seconds: current.seconds + seconds });
+    }
+    const days = Array.from({ length: trackedDays }, (_, index) => {
+        const date = addLocalDays(firstDay, index);
+        const key = localDay(date);
+        return { date: key, seconds: secondsByDay.get(key) ?? 0 };
+    });
+    const activeDays = days.filter(day => day.seconds > 0).length;
+    let favorite = null;
+    for (const entry of secondsByStation.values()) {
+        if (!favorite || entry.seconds > favorite.seconds) {
+            favorite = entry;
+        }
+    }
+    return {
+        favoriteStation: favorite?.station ?? null,
+        listenedStationCount: Array.from(secondsByStation.values()).filter(entry => entry.seconds >= listenedStationThresholdSeconds).length,
+        sessions: sessions.length,
+        currentStreak: currentStreak(days),
+        activeDays,
+        totalTrackedDays: trackedDays,
+        totalSeconds,
+        longestStreak: longestStreak(days),
+        days
+    };
+}
+function sessionSeconds(session, now = new Date()) {
+    const started = Date.parse(session.startedAt);
+    const ended = session.endedAt ? Date.parse(session.endedAt) : now.getTime();
+    if (!Number.isFinite(started) || !Number.isFinite(ended) || ended <= started) {
+        return Math.max(0, Math.round(session.listenedSeconds));
+    }
+    return Math.max(Math.round(session.listenedSeconds), Math.round((ended - started) / 1000));
+}
+function localDay(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+function splitSessionByDay(session, seconds, firstDay, lastDayEnd, now) {
+    const started = Date.parse(session.startedAt);
+    if (!Number.isFinite(started)) {
+        return [];
+    }
+    const recordedEnd = session.endedAt ? Date.parse(session.endedAt) : now.getTime();
+    const rawEnd = Number.isFinite(recordedEnd) && recordedEnd > started
+        ? recordedEnd
+        : started + seconds * 1000;
+    const end = Math.max(started, rawEnd);
+    const boundedStart = Math.max(started, firstDay.getTime());
+    const boundedEnd = Math.min(end, lastDayEnd.getTime());
+    if (boundedEnd <= boundedStart) {
+        return [];
+    }
+    const allocations = [];
+    let cursor = boundedStart;
+    while (cursor < boundedEnd) {
+        const dayStart = startOfLocalDay(new Date(cursor)).getTime();
+        const nextDay = addLocalDays(new Date(dayStart), 1).getTime();
+        const segmentEnd = Math.min(nextDay, boundedEnd);
+        allocations.push({
+            date: localDay(new Date(cursor)),
+            seconds: Math.round((segmentEnd - cursor) / 1000)
+        });
+        cursor = segmentEnd;
+    }
+    return allocations;
+}
+function startOfLocalDay(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+function addLocalDays(date, days) {
+    const next = new Date(date.getTime());
+    next.setDate(next.getDate() + days);
+    return startOfLocalDay(next);
+}
+function currentStreak(days) {
+    let streak = 0;
+    for (let index = days.length - 1; index >= 0; index -= 1) {
+        if (days[index].seconds <= 0) {
+            break;
+        }
+        streak += 1;
+    }
+    return streak;
+}
+function longestStreak(days) {
+    let longest = 0;
+    let current = 0;
+    for (const day of days) {
+        if (day.seconds > 0) {
+            current += 1;
+            longest = Math.max(longest, current);
+        }
+        else {
+            current = 0;
+        }
+    }
+    return longest;
+}