Aurora SpotiRip desktop and web app

- Spotify playlist, library, album and artist browsing with in-app playback
- Song, playlist and album downloads via spotdl with YouTube and Bandcamp fallbacks
- Electron desktop app (castLabs Widevine) with a permanent sidebar layout
- Linux and Windows packaging scripts

docs/self-hosting.md

@@ -0,0 +1,72 @@
+Aurora SpotiRip self-host deployment
+
+Production URL
+- https://spotirip.auroradragon.dev
+
+Server requirements
+- Node.js 22+ and pnpm (`npm install -g pnpm`).
+- Python 3.10+ with the venv module (Debian/Ubuntu: `sudo apt install python3-venv`).
+- ffmpeg (`sudo apt install ffmpeg`, or `venv/bin/spotdl --download-ffmpeg`).
+- A long-running Node process (server.ts). Downloads run as background jobs held in memory,
+  so a serverless runtime will not work.
+
+Setup (run inside the app folder)
+1. python3 -m venv venv
+2. venv/bin/pip install spotdl
+3. pnpm install
+4. Fill in env.json (see below).
+5. pnpm vite build
+6. pnpm tsx server.ts   (listens on http://localhost:3333)
+
+env.json
+- SPOTIRIP_BASE_URL=https://spotirip.auroradragon.dev
+- SPOTIFY_CLIENT_ID=<Spotify Developer Dashboard client id>
+- SPOTIFY_CLIENT_SECRET=<Spotify Developer Dashboard client secret>
+- AUDD_API_TOKEN=<AudD API token>
+- SPOTIRIP_DOWNLOAD_USERS="*" lets every connected Spotify account download. Set a comma-separated
+  list of Spotify user ids to restrict it. The check lives in isDownloadAllowed()
+  (helpers/downloadJobs.tsx); swap it for site logins later.
+- SPOTIRIP_PYTHON=venv/bin/python (path to the venv's Python, relative to the app folder)
+- SPOTIRIP_DOWNLOADER=spotify_downloader.py (optional; path to the downloader script)
+
+Spotify Developer Dashboard
+- Website: https://spotirip.auroradragon.dev
+- Redirect URI: https://spotirip.auroradragon.dev/spotify/callback
+- In Development Mode Spotify only lets allow-listed accounts (max 25) sign in. Other visitors need
+  the app to be granted Extended Quota Mode.
+
+How downloads work
+- The download button POSTs the track link(s) to /_api/spotify-download. Playlists are sent as their
+  individual track links, so private playlists work.
+- The server runs spotify_downloader.py (spotdl) into a temporary folder; the page polls
+  /_api/spotify-download-status for progress.
+- When finished, the browser is sent to /_api/spotify-download-file, which returns the MP3 (single track)
+  or a zip named after the playlist as an attachment, then deletes the server copy.
+- Audio comes from YouTube Music. Songs that fail there are retried with a regular YouTube search,
+  then Bandcamp (FALLBACK_PROVIDERS in spotify_downloader.py). Songs that still fail are skipped and
+  named in the server log ("could not download ...").
+- yt-dlp needs a JavaScript runtime for YouTube; the server passes its own Node binary automatically.
+- Unclaimed downloads are deleted after 30 minutes. Limits: 1 running download per user, 2 overall
+  (MAX_RUNNING_JOBS in helpers/downloadJobs.tsx).
+
+Reverse proxy
+- Proxy the public domain to port 3333 (Nginx, Apache, Caddy, ...).
+- Preserve Set-Cookie headers. Spotify session cookies are Secure, HttpOnly and SameSite=Lax.
+- Allow large responses (playlist zips can be hundreds of MB); with Nginx set
+  `proxy_max_temp_file_size 0;` or `proxy_buffering off;` for /_api/spotify-download-file.
+- Serve the SPA with history fallback so /identify, /library, /spotify-library, /artist/:id, /album/:id
+  and /spotify/callback resolve (server.ts already does this).
+
+Browser requirements for local-library features
+- File System Access API features work best in Chromium-based browsers over HTTPS.
+- When direct folder writing is unavailable, SpotiRip falls back to normal browser downloads.
+
+Production verification after deployment
+1. Open https://spotirip.auroradragon.dev.
+2. Connect Spotify and approve the requested scopes.
+3. Verify the callback returns to /spotify/callback and then to the home page.
+4. Load a playlist; download one track (MP3) and the whole playlist (zip).
+5. Test playlist import, My Spotify, Web Playback SDK playback, album/artist browsing and lyrics.
+6. Test Identify with a real local music file.
+7. Test Convert, Analyzer, Local Library scan and organizer.
+8. Confirm mobile bottom navigation and compact player on a phone.