- search page with a 250 ms pause after typing, the text kept in the address, and at most 200 characters sent
- artists, albums and songs in three groups of six, each with a link to the full list
- accents and capitals are left to the server, which ignores them
- list hooks can take a smaller page size and stay switched off until there is something to ask
- lists of artists, albums and songs, loaded 50 at a time, with the search text taken from the address
- album page and artist page; a click on a song plays the list from there
- artist page shows a Wikipedia text, similar artists and tags with their credits, and the photo credit
- providers that are off, unreachable or without an id give a short explanation, never an error page
- artists a provider named, with nothing to play, still have a page
- bar at the bottom of every page with cover, artists, controls, seek and time
- full-screen player in a dialog: big cover, bar-style seek control, up next, focus kept inside, Escape closes
- Space plays and pauses unless the key belongs to a field, a button or a link
- songs list row, seek control and time formatting
- jumpTo in the queue store for a click on an upcoming track
- one event per play with its own idempotency key: complete, skip, or play when the page closes
- a failed send is retried with the same body and key after 1, 4 and 16 seconds; a 400 or 404 is final
- closing the page sends the open play and anything waiting for a retry with keepalive
- a hidden tab keeps playing, so only pagehide ends a play early
- drives the audio element from the player store: load, play, pause, seek, next on end
- a renewed access token swaps the stream URL and resumes at the same second, playing or paused
- reports start, listened time (in steps of at most two seconds) and finish for the listen reporter
- media keys and lock screen through the Media Session API
- queue with next, previous, seek, repeat (off, all, one), shuffle that keeps the original order, enqueue, play next and remove
- seek and restart requests are explicit, so the audio engine can follow them
- sidebar with the current page marked, privacy note, and a main area that wraps on narrow screens
- routes for home, search, artists, albums, songs and settings, and a not-found page
- paged lists for artists, albums and songs, 50 at a time, with search text and artist/album filters
- cover and artist photo that fall back to rings or an initial, and retry when the token is renewed
- fetch client with bearer token, one retry after a renewal, ApiError with the server code
- session kept in localStorage; renewal is single-flight in a tab and under a Web Lock across tabs, and a tab adopts a session another tab already renewed
- a refused refresh token signs out once; an unreachable server keeps the session
- mediaUrl and onTokenChange for audio and image URLs that carry the token
- sign-in and first-account screen, and a gate that shows the app only when signed in
- i18next with en and it, language from the stored choice, then the browser, then English
- a test keeps both files on the same keys with no empty text
- API error codes map to error.<code>, with error.unknown as the fallback
- Sonda, Tokyo Night, Gruvbox dark and Gruvbox light as CSS variables with shadcn token names
- contrast test: text 4.5:1, accent and form outlines 3:1 in every theme
- Gruvbox dark muted text lightened to pass
- theme choice is stored in localStorage and survives it being blocked
- Vite, React 19 and TypeScript in web/, Vitest with jsdom and Testing Library
- Tailwind v4 and shadcn/ui, with Figtree and Fraunces bundled locally
- npm run gen:api builds src/api/schema.d.ts from the OpenAPI spec
- dev server proxies /api to sondad (SONDA_URL, default 127.0.0.1:8080)
- mockFetch test helper that refuses unmatched requests