# Music_Server Inline Lyrics Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make `Music_Server` include local `.lrc` content as `rawLrc` in distributed song items and keep the MusicFree plugins passing that field through.

**Architecture:** Extend catalog track queries to expose the best local file locator, resolve a sibling `.lrc` under `LOCAL_LIBRARY_ROOT`, and inject the text into the existing song payload builder. Update both served plugin assets so their `mapMusicItem()` output preserves `rawLrc`.

**Tech Stack:** Python 3.11, FastAPI, sqlite3, unittest, plain JavaScript plugin assets.

---

### Task 1: Add failing backend and plugin tests

**Files:**
- Modify: `tests/test_mf_catalog_routes.py`
- Modify: `tests/test_plugin_routes.py`

- [ ] Add route assertions that expect `rawLrc` when a same-name `.lrc` exists beside a local audio file.
- [ ] Add route assertions that verify requests still succeed without `LOCAL_LIBRARY_ROOT`.
- [ ] Add plugin asset assertions that both served JS assets contain `rawLrc` mapping code.
- [ ] Run only the new/updated tests and confirm they fail for the expected missing-lyrics behavior.

### Task 2: Implement inline lyric loading

**Files:**
- Modify: `src/music_server/services/catalog_reader.py`
- Modify: `src/music_server/routes/mf_catalog.py`

- [ ] Extend track row queries to expose the preferred active `local_fs` locator for each song.
- [ ] Add a helper that safely resolves a sibling `.lrc` under `LOCAL_LIBRARY_ROOT` and reads it as text.
- [ ] Inject `rawLrc` into `_to_music_item()` only when a lyric file is present.
- [ ] Re-run the focused backend tests and confirm they pass.

### Task 3: Preserve lyrics in plugin assets

**Files:**
- Modify: `src/music_server/plugin_assets/music_server.js`
- Modify: `src/music_server/plugin_assets/music_server_lan.js`
- Test: `tests/test_plugin_routes.py`

- [ ] Update `mapMusicItem()` in both plugin assets to copy `rawLrc` from the server payload.
- [ ] Re-run the plugin asset tests and confirm they pass.

### Task 4: Verify the feature end to end in repo tests

**Files:**
- Modify: none

- [ ] Run the focused unittest command for `test_mf_catalog_routes` and `test_plugin_routes`.
- [ ] If those pass, run `test_catalog_reader.py` as a regression check for reader query changes.
- [ ] Record any deployment-only follow-up separately; do not expand scope in code.