mcma-webui/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Web UI for a self-hosted music service (MCMA). Role: control center — library, downloads, storage, users/permissions. Playback exists (persistent player) but is secondary to a future mobile client.

Commands

• npm run dev — dev server at http://localhost:3000
• npm run build — production build
• npm run preview — preview production build
• npm run lint — rslint (@rslint/core, native-speed lint)
• npm run test — rstest (run once); npm run test:watch — watch mode
• npm run format — prettier
• npx tsc --noEmit — typecheck (strict; this is the main correctness gate, lint does not type-check)

Single test: npx rstest tests/index.test.tsx (path or -t <name pattern>).

Stack (fixed — do not swap)

React 19 + TypeScript strict · rsbuild (not Vite/CRA) · RTK Query for all server state · Redux Toolkit slices for client state · React Router · modern-sk UI kit. React Compiler is enabled via babel-plugin-react-compiler — do not hand-add useMemo/useCallback for render-identity reasons; the compiler handles memoization.

Hard rules (architecture invariants)

1. No hardcoded backend address except the env default. Runtime override is mandatory (see base-URL resolution below).
2. No fetch in components. All backend access goes through RTK Query hooks. The entire API surface is isolated in src/api/. The one sanctioned exception is useConnectionStatus (health ping) and the audio <audio>.src stream URL — these are not data fetches.
3. No server data duplicated into Redux slices. Slices hold only client state (player, queue, ui, auth tokens). Track lists live in the RTKQ cache; the play queue stores track IDs + minimal display fields, not full records.
4. UI is built only from modern-sk. No MUI/AntD/shadcn. Missing component → compose from modern-sk primitives. Import its CSS once at the entry (modern-sk/styles.css, modern-sk/fonts.css). Wrap the app in <ThemeProvider> + <TooltipProvider>. The grained black page background comes from the .modern-sk-felt class — applied to #root in src/index.tsx; without it the page is bare white. modern-sk sets font-family only on its own component classes, so src/styles/global.css sets the base font-family: var(--font-sans) on body (else plain elements fall back to browser serif).
   • Token names: modern-sk's real tokens are --ink/--ink-raised, --fg-1/2/3, --steel-700/800, --lime, --hair. Our component code uses semantic aliases (--color-bg, --color-surface-1/2/3, --color-text-1/2/3, --color-accent, --color-border) defined in src/styles/global.css as var() refs to the real tokens (so they follow [data-theme]). Use the --color-* aliases in app code; add a new alias there if you need another token.
5. One <audio> element for the whole app. It is a module-level singleton in useAudioPlayer.ts, deliberately outside the React tree so navigation never recreates it.
6. Every list screen needs all three states: LoadingSkeleton, EmptyState, ErrorState (in src/components/common/). No bare loading.
7. Strict TS, no any in API types or public module interfaces.

Backend contract

UI is backend-agnostic: it targets the /api/v1 contract, not a specific server. src/api/types.ts is the single source of truth for contract types — keep it synced with the backend plan (music-selfhost-backend-plan.md §8). Swapping/mocking the backend = change baseQuery, nothing else.

How the pieces connect

Base-URL resolution (src/config/): priority is localStorage (user-chosen via ConnectPage) > PUBLIC_API_BASE_URL env > relative /api/v1. runtime-config.ts reads/writes the localStorage override; getApiBaseUrl() is called by baseQuery, the stream-URL builder, and the health check.

API layer (src/api/): index.ts creates the single api via createApi with tagTypes (Track, Album, Artist, Playlist, Download, Like, User, Storage). Endpoints are split by domain under endpoints/ and attached with injectEndpoints — each file exports its own hooks. These files must be imported for their side effect (endpoint registration); src/index.tsx imports all of them at startup. baseQuery.ts does dynamic base URL + Authorization: Bearer injection + 401→refresh→retry reauth (falls back to logout() on refresh failure). Mutations invalidate tags to drive refetch.

Store (src/store/): configureStore wires api.reducer + api.middleware alongside slices. RootState/AppDispatch exported here; typed hooks in src/hooks/useAppDispatch.ts (useAppDispatch, useAppSelector). Slices: auth (tokens + user, persisted to localStorage key mcma_auth), player (currentTrackId/isPlaying/position/volume/repeat/shuffle/panel toggles), queue (entries + currentIndex + source), ui (sidebar/modal/context-menu).

Audio flow: useAudioPlayer syncs the singleton <audio> ↔ player slice. Queue currentIndex change → sets player.currentTrackId → effect points <audio>.src at getStreamUrl(trackId, token) (token as query param) → play/pause mirrors player.isPlaying. <audio> events (timeupdate, ended, etc.) dispatch back into the slice. MediaSession integration is a planned stub here.

Routing (src/routes/): ProtectedRoute gates on auth token + user, with requireAdmin. Unauthed → /connect. index.tsx lazy-loads non-core feature pages. Permission checks via usePermissions (role→permission map, MVP admin/user, designed to extend to granular perms — gate UI on hasPermission(...), not raw role).

Layout: AppShell = Sidebar + <Outlet/> + PersistentPlayer (bottom, persists across routes) + collapsible QueuePanel.

Project layout

src/api/ backend access · src/store/slices/ client state · src/features/<screen>/ screen-as-feature (one folder per A-screen) · src/components/{layout,player,track,common}/ reusable compositions · src/hooks/ · src/lib/ (formatters) · src/config/ · src/routes/.

Screens follow a spec (music-selfhost-screens.md, parts A1–A11). Implemented as reference: Library (A2), Album/Playlist detail (A3). Others are stub pages under src/features/ + routes — adding a screen is meant to be mechanical: fill the stub, wire RTKQ hooks, reuse common state components + TrackRow/TrackContextMenu.

Cross-cutting components (build/reuse before screens)

AvailabilityBadge (track availability: server/downloading/error/missing), TrackRow + TrackContextMenu (used in every track list), ConnectionStatus (global instance reachability), and the three list states above.

Gotcha

tests/index.test.tsx is the stale rsbuild scaffold test importing a now-deleted src/App — it will fail until rewritten. The entry point is src/index.tsx (there is no App.tsx).