refactor: remove legacy single-root APIs, defer filesystem I/O, enforce POSIX paths

- Remove legacy endpoints: /api/change-folder, /api/index, /api/scan, /api/status,
  /api/playback/resume-positions
- Remove legacy global scanner module-level API from hivescan/scanner.py
- Defer all filesystem validation to background task in server lifespan (macOS-safe)
- CLI and winmain pass raw paths via MEDIAHIVE_ROOTS; no pre-startup validation
- Enforce POSIX paths everywhere (as_posix(), no backslash leakage)
- Remove MEDIAHIVE_PATH and MEDIAHIVE_DEFER_INITIAL_ROOT env vars
- Update frontend api.ts to use per-root resume positions
- Update docs/API.md and docs/multi-index-plan.md
- Fix Python 2 style except clauses in hivescan/utils.py and scanning.py

docs/API.md

@@ -1,29 +1,31 @@
 # API
 
 MediaHive exposes a small local API used by the desktop app and frontend.
+All media paths are scoped to a **root**, identified by a stable `root_id`.
 
 ## Endpoints
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/api/health` | Lightweight health check. |
-| `GET` | `/api/config` | Returns the currently selected media folder. |
-| `POST` | `/api/change-folder` | Persists and switches the active media folder without restarting the app. |
-| `GET` | `/api/index` | Returns the current in-memory media index. |
-| `GET` | `/api/playback/resume-positions` | Returns saved resume positions by media path. |
-| `GET` | `/api/status` | Returns scanner and library status information. |
-| `POST` | `/api/scan` | Triggers a new scan if the scanner is active. |
-| `POST` | `/api/play` | Opens a media file with the system player. |
-| `POST` | `/api/open-folder` | Opens a folder in the system file explorer, or selects a file in its parent folder. |
+| `GET` | `/api/config` | Returns the current root configuration. |
+| `GET` | `/api/roots` | List all active roots with status. |
+| `PUT` | `/api/roots` | Atomically replace the full root set. |
+| `GET` | `/api/roots/{root_id}/index` | Returns the media index for one root. |
+| `GET` | `/api/roots/{root_id}/status` | Returns scanner and library status for one root. |
+| `POST` | `/api/roots/{root_id}/scan` | Triggers a new scan for one root. |
+| `POST` | `/api/roots/{root_id}/play` | Opens a media file with the system player. |
+| `POST` | `/api/roots/{root_id}/open-folder` | Opens a folder in the system file explorer. |
+| `GET` | `/api/roots/{root_id}/playback/resume-positions` | Returns saved resume positions for one root. |
 | `GET` | `/api/player/status` | Returns whether remote player control is currently available. |
 | `GET` | `/api/mpcbe/status` | Reports whether MPC-BE's local web interface is reachable. |
-| `GET` | `/api/media/{file_path:path}` | Serves files from the active media root. |
-| `WS` | `/api/ws` | Streams live index updates and task progress events. |
+| `GET` | `/api/media/{root_id}/{file_path:path}` | Serves files from the specified root. |
+| `WS` | `/api/roots/{root_id}/ws` | Streams live index updates and task progress for one root. |
 
 ## Notes
 
-- `POST /api/change-folder` validates the new folder, saves it to config, and switches the in-memory scanner asynchronously.
-- `POST /api/play` and `POST /api/open-folder` expect JSON request bodies matching the frontend calls.
-- `GET /api/media/{file_path:path}` is constrained to the current media root.
+- `PUT /api/roots` accepts `{ "roots": { "name": "/absolute/path", ... } }`, validates paths, and atomically swaps the active set.
+- `POST /api/roots/{root_id}/play` and `POST /api/roots/{root_id}/open-folder` expect JSON request bodies with `file_path` / `folder_path` relative to the root.
+- `GET /api/media/{root_id}/{file_path:path}` is constrained to the specified root; path traversal outside the root is rejected.
 - `GET /api/player/status` returns `{ "remote": true|false }`.
 - `GET /api/mpcbe/status` returns `false` on non-Windows platforms.