Merge branch 'dev'

docs/ZXDB.md

@@ -39,6 +39,34 @@ Notes:
 - The URL must start with `mysql://`. Env is validated at boot by `src/env.ts` (Zod), failing fast if misconfigured.
 - The app uses a singleton `mysql2` pool (`src/server/db.ts`) and Drizzle ORM for typed queries.
 
+### Local File Mirrors
+
+The explorer can optionally show "Local Mirror" links for downloads if you have local copies of the ZXDB and World of Spectrum (WoS) file archives.
+
+#### Configuration
+
+To enable local mirrors, set the following variables in your `.env`:
+
+```bash
+# Absolute paths to your local mirrors
+ZXDB_LOCAL_FILEPATH=/path/to/your/zxdb/mirror
+WOS_LOCAL_FILEPATH=/path/to/your/wos/mirror
+
+# Optional: Remote path prefixes to strip from database links before prepending local paths
+ZXDB_FILE_PREFIX=/zxdb/sinclair/
+WOS_FILE_PREFIX=/pub/sinclair/
+```
+
+#### How it works
+
+1. The app identifies if a download link matches `ZXDB_FILE_PREFIX` or `WOS_FILE_PREFIX`.
+2. It strips the prefix from the database link.
+3. It joins the remaining relative path to the corresponding `*_LOCAL_FILEPATH`.
+4. It checks if the file exists on the local disk.
+5. If the file exists and the environment variable is set, a "Local Mirror" link is displayed in the UI, pointing to a proxy download API (`/api/zxdb/download`).
+
+Note: Obtaining these mirrors is left as an exercise to the host. The paths do not need to share a common parent directory. Both mirrors are optional and independent; you can configure one, both, or neither.
+
 ## Running
 
 ```