diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 2fa4340..dab5a0b 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -137,55 +137,55 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| SCAN-01 | — | Pending | -| SCAN-02 | — | Pending | -| SCAN-03 | — | Pending | -| KEY-01 | — | Pending | -| KEY-02 | — | Pending | -| KEY-03 | — | Pending | -| KEY-04 | — | Pending | -| KEY-05 | — | Pending | -| TAG-01 | — | Pending | -| TAG-02 | — | Pending | -| TAG-03 | — | Pending | -| TAG-04 | — | Pending | -| TAG-05 | — | Pending | -| TAG-06 | — | Pending | -| TAG-07 | — | Pending | -| SMRT-01 | — | Pending | -| SMRT-02 | — | Pending | -| SMRT-03 | — | Pending | -| SMRT-04 | — | Pending | -| SMRT-05 | — | Pending | -| GAP-01 | — | Pending | -| GAP-02 | — | Pending | -| GAP-03 | — | Pending | -| GAP-04 | — | Pending | -| MB-01 | — | Pending | -| MB-02 | — | Pending | -| MB-03 | — | Pending | -| MB-04 | — | Pending | -| MB-05 | — | Pending | -| MB-06 | — | Pending | -| MB-07 | — | Pending | -| LAYOUT-01 | — | Pending | -| LAYOUT-02 | — | Pending | -| LAYOUT-03 | — | Pending | -| LAYOUT-04 | — | Pending | -| LAYOUT-05 | — | Pending | -| LAYOUT-06 | — | Pending | -| PLUG-01 | — | Pending | -| PLUG-02 | — | Pending | -| PLUG-03 | — | Pending | -| PLUG-04 | — | Pending | -| PLUG-05 | — | Pending | -| PLUG-06 | — | Pending | +| SCAN-01 | Phase 9 | Pending | +| SCAN-02 | Phase 9 | Pending | +| SCAN-03 | Phase 9 | Pending | +| KEY-01 | Phase 9 | Pending | +| KEY-02 | Phase 9 | Pending | +| KEY-03 | Phase 9 | Pending | +| KEY-04 | Phase 9 | Pending | +| KEY-05 | Phase 9 | Pending | +| TAG-01 | Phase 10 | Pending | +| TAG-02 | Phase 10 | Pending | +| TAG-03 | Phase 10 | Pending | +| TAG-04 | Phase 10 | Pending | +| TAG-05 | Phase 10 | Pending | +| TAG-06 | Phase 10 | Pending | +| TAG-07 | Phase 10 | Pending | +| SMRT-01 | Phase 11 | Pending | +| SMRT-02 | Phase 11 | Pending | +| SMRT-03 | Phase 11 | Pending | +| SMRT-04 | Phase 11 | Pending | +| SMRT-05 | Phase 11 | Pending | +| GAP-01 | Phase 12 | Pending | +| GAP-02 | Phase 12 | Pending | +| GAP-03 | Phase 12 | Pending | +| GAP-04 | Phase 12 | Pending | +| MB-01 | Phase 13 | Pending | +| MB-02 | Phase 13 | Pending | +| MB-03 | Phase 13 | Pending | +| MB-04 | Phase 13 | Pending | +| MB-05 | Phase 13 | Pending | +| MB-06 | Phase 13 | Pending | +| MB-07 | Phase 13 | Pending | +| LAYOUT-01 | Phase 14 | Pending | +| LAYOUT-02 | Phase 14 | Pending | +| LAYOUT-03 | Phase 14 | Pending | +| LAYOUT-04 | Phase 14 | Pending | +| LAYOUT-05 | Phase 14 | Pending | +| LAYOUT-06 | Phase 14 | Pending | +| PLUG-01 | Phase 14 | Pending | +| PLUG-02 | Phase 14 | Pending | +| PLUG-03 | Phase 14 | Pending | +| PLUG-04 | Phase 14 | Pending | +| PLUG-05 | Phase 14 | Pending | +| PLUG-06 | Phase 14 | Pending | **Coverage:** - v1.1 requirements: 43 total -- Mapped to phases: 0 -- Unmapped: 43 +- Mapped to phases: 43 +- Unmapped: 0 ✓ --- *Requirements defined: 2026-03-06* -*Last updated: 2026-03-06 after initial definition* +*Last updated: 2026-03-06 — traceability updated with phase mappings* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index fc12981..e43a136 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -1,8 +1,13 @@ # Roadmap: YellowJacket +**Created:** 2026-02-27 +**Last updated:** 2026-03-06 +**Current milestone:** v1.1 Features & Extensibility + ## Milestones - ✅ **v1.0 Consolidation** — Phases 1-8 (shipped 2026-03-05) — [archive](milestones/v1.0-ROADMAP.md) +- 🔄 **v1.1 Features & Extensibility** — Phases 9-14 (in progress) ## Phases @@ -20,6 +25,87 @@ +### v1.1 Features & Extensibility (Phases 9-14) + +- [ ] **Phase 9: Scan Cancellation & Keyboard Shortcuts** — Cancellable library scans and configurable keyboard shortcuts +- [ ] **Phase 10: Tag Editing** — Edit track metadata and write changes to audio files +- [ ] **Phase 11: Smart Playlists** — Auto-generated playlists with filter rules +- [ ] **Phase 12: Gapless Playback & Crossfade** — Seamless track transitions with optional crossfade +- [ ] **Phase 13: MusicBrainz Browser** — Browse the MusicBrainz catalog from within the app +- [ ] **Phase 14: Layout Customization & Plugin Foundation** — Section-based UI customization and JS plugin system + +## Phase Details + +### Phase 9: Scan Cancellation & Keyboard Shortcuts +**Goal:** Users can control library scans (cancel/pause/resume) and operate the entire app via keyboard +**Depends on:** Nothing (builds on v1.0 foundation) +**Requirements:** SCAN-01, SCAN-02, SCAN-03, KEY-01, KEY-02, KEY-03, KEY-04, KEY-05 +**Success Criteria** (what must be TRUE): + 1. User can click a cancel button during a library scan and the scan stops within seconds — no database corruption, no orphaned tracks + 2. User can pause a running scan and resume it later without re-processing files that were already scanned + 3. Default keyboard shortcuts work immediately after install — play/pause, next/prev, volume up/down, search focus, queue toggle, shuffle, repeat all respond to keys + 4. User can open a settings UI, rebind any shortcut to a different key, and the new binding takes effect immediately — conflicts are warned about before saving + 5. Keyboard shortcuts are context-aware — typing in a search box doesn't trigger player shortcuts (except Escape to blur) +**Plans:** TBD + +### Phase 10: Tag Editing +**Goal:** Users can edit track metadata from within the app and changes are written to the actual audio files +**Depends on:** Phase 9 (scan cancellation validates context patterns; tag edits must be blocked during active scans) +**Requirements:** TAG-01, TAG-02, TAG-03, TAG-04, TAG-05, TAG-06, TAG-07 +**Success Criteria** (what must be TRUE): + 1. User can select a track, edit its title/artist/album/genre/year/track number in a UI form, and save — the changes appear immediately in the library without requiring a rescan + 2. User can select multiple tracks, edit shared fields (e.g., album name, genre), and the batch edit applies to all selected tracks + 3. Tag changes are persisted to the actual MP3 (ID3v2) and FLAC (Vorbis Comments) files on disk — verified by re-reading the file's metadata + 4. User can assign or replace embedded cover art from an image file, and the new art displays immediately + 5. A file that is currently playing cannot have its tags edited — the UI shows a clear indication that the edit is blocked until playback moves on +**Plans:** TBD + +### Phase 11: Smart Playlists +**Goal:** Users can create rule-based playlists that automatically populate based on their music library metadata +**Depends on:** Phase 10 (tag editing validates DB update + event pipeline; edited metadata affects smart playlist membership) +**Requirements:** SMRT-01, SMRT-02, SMRT-03, SMRT-04, SMRT-05 +**Success Criteria** (what must be TRUE): + 1. User can create a smart playlist with one or more filter rules (genre equals "Jazz", year > 2000, artist contains "Miles") and see matching tracks + 2. Multiple rules combine with AND logic — adding a second rule narrows the results + 3. User can set random ordering and a result limit (e.g., "Random 50 Jazz tracks") and the playlist respects both + 4. Smart playlists appear in the sidebar alongside regular playlists with a distinct icon, and their rules persist across app restarts +**Plans:** TBD + +### Phase 12: Gapless Playback & Crossfade +**Goal:** Tracks transition seamlessly with no audible gap, and users can optionally enable crossfade between tracks +**Depends on:** Phase 9 (keyboard shortcuts needed for testing audio transitions; no direct code dependency but risk isolation — this is the highest-risk phase) +**Requirements:** GAP-01, GAP-02, GAP-03, GAP-04 +**Success Criteria** (what must be TRUE): + 1. When playing an album, tracks transition with no audible silence gap — the audio stream is continuous + 2. The next track is pre-decoded before the current track ends so the transition is instantaneous + 3. User can enable crossfade in settings with a configurable duration (1-10 seconds), and tracks blend smoothly during auto-advance + 4. Crossfade only applies on auto-advance (track finishes naturally) — manual skip/next produces an immediate clean switch +**Plans:** TBD + +### Phase 13: MusicBrainz Browser +**Goal:** Users can browse the MusicBrainz music catalog (artists, albums, tracks) directly from within the app +**Depends on:** Phase 11 (smart playlists validate dynamic DB query patterns reused by MB cache; no hard dependency but ordering isolates network feature) +**Requirements:** MB-01, MB-02, MB-03, MB-04, MB-05, MB-06, MB-07 +**Success Criteria** (what must be TRUE): + 1. User can search for an artist by name and see a list of matching results from MusicBrainz + 2. User can select an artist and browse their discography — albums, EPs, and singles displayed as release groups + 3. User can view the track listing for a specific release and see different editions (original, reissue, deluxe) of a release group + 4. Album cover art from the Cover Art Archive is displayed alongside release information + 5. The app respects MusicBrainz rate limits (1 req/sec), caches responses in SQLite (24hr searches, 7 days entities), and works gracefully when offline or rate-limited +**Plans:** TBD + +### Phase 14: Layout Customization & Plugin Foundation +**Goal:** Users can customize the app's layout (resize, show/hide, rearrange panels) and developers can extend the app with JavaScript plugins +**Depends on:** Phase 13 (layout and plugin systems wrap all existing features — needs stable component set and API surface) +**Requirements:** LAYOUT-01, LAYOUT-02, LAYOUT-03, LAYOUT-04, LAYOUT-05, LAYOUT-06, PLUG-01, PLUG-02, PLUG-03, PLUG-04, PLUG-05, PLUG-06 +**Success Criteria** (what must be TRUE): + 1. User can drag to resize the sidebar and queue panels, and the sizes persist across app restarts + 2. User can show/hide sidebar sections and the queue panel, and choose which component is displayed in each layout section + 3. Layout presets (Compact, Full, Mini player) are available and the user can quick-switch between them + 4. A JS/TS plugin loaded from the user's plugin directory can access player state, queue data, and library data via a defined API, and can register a custom UI component into the layout + 5. An example plugin ships with the app demonstrating the plugin API (manifest, configuration, event hooks, UI registration) +**Plans:** TBD + ## Progress | Phase | Milestone | Plans Complete | Status | Completed | @@ -32,7 +118,13 @@ | 6. SQL Consolidation & Code Quality | v1.0 | 3/3 | Complete | 2026-03-04 | | 7. Backend Performance | v1.0 | 2/2 | Complete | 2026-03-05 | | 8. Frontend Performance & UX | v1.0 | 4/4 | Complete | 2026-03-05 | +| 9. Scan Cancellation & Keyboard Shortcuts | v1.1 | 0/? | Not started | - | +| 10. Tag Editing | v1.1 | 0/? | Not started | - | +| 11. Smart Playlists | v1.1 | 0/? | Not started | - | +| 12. Gapless Playback & Crossfade | v1.1 | 0/? | Not started | - | +| 13. MusicBrainz Browser | v1.1 | 0/? | Not started | - | +| 14. Layout Customization & Plugin Foundation | v1.1 | 0/? | Not started | - | --- *Roadmap created: 2026-02-27* -*Last updated: 2026-03-05 — v1.0 milestone archived* +*Last updated: 2026-03-06 — v1.1 phases 9-14 added* diff --git a/.planning/STATE.md b/.planning/STATE.md index e2e44a3..ceb334c 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,10 +2,10 @@ gsd_state_version: 1.0 milestone: v1.1 milestone_name: Features & Extensibility -status: defining_requirements +status: roadmap_complete last_updated: "2026-03-06" progress: - total_phases: 0 + total_phases: 6 completed_phases: 0 total_plans: 0 completed_plans: 0 @@ -18,14 +18,31 @@ progress: See: .planning/PROJECT.md (updated 2026-03-06) **Core value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy. -**Current focus:** v1.1 Features & Extensibility — defining requirements +**Current focus:** v1.1 Features & Extensibility — roadmap complete, ready for planning ## Current Position -Phase: Not started (defining requirements) +Phase: 9 — Scan Cancellation & Keyboard Shortcuts Plan: — -Status: Defining requirements -Last activity: 2026-03-06 — Milestone v1.1 started +Status: Ready for planning +Progress: ░░░░░░░░░░░░░░░░░░░░ 0/6 phases (0%) +Last activity: 2026-03-06 — Roadmap created for v1.1 + +### Phase Overview + +| Phase | Status | +|-------|--------| +| 9. Scan Cancellation & Keyboard Shortcuts | Not started | +| 10. Tag Editing | Not started | +| 11. Smart Playlists | Not started | +| 12. Gapless Playback & Crossfade | Not started | +| 13. MusicBrainz Browser | Not started | +| 14. Layout Customization & Plugin Foundation | Not started | + +## Performance Metrics + +**v1.0 baseline:** 8 phases, 17 plans, 34 tasks in 6 days (107 commits) +**v1.1 scope:** 6 phases, 43 requirements, ~? plans (TBD during planning) ## Accumulated Context @@ -40,22 +57,44 @@ Decisions from v1.0 are archived in PROJECT.md Key Decisions table. Key patterns - queueMicrotask coalescing for store notifications - `.renderItem` + `.keyFunction` (not `repeat()` children) for lit-virtualizer +### v1.1 Roadmap Decisions + +| Decision | Rationale | +|----------|-----------| +| Phase 9 = Scan Cancel + Shortcuts | Quick wins, validate context cancellation and config extension patterns | +| Phase 10 = Tag Editing after shortcuts | Introduces 3 new deps, file-write-DB-event pipeline; benefits from validated patterns | +| Phase 11 = Smart Playlists after tags | DB patterns, benefits from validated DB update pipeline | +| Phase 12 = Gapless mid-sequence | Highest risk isolated after foundations proven, before meta-features | +| Phase 13 = MusicBrainz after gapless | First network feature, orthogonal to audio work | +| Phase 14 = Layout + Plugins last | Meta-features that wrap all others, need stable API surface | +| Layout + Plugins combined into one phase | Both are extensibility foundations; layout provides component registry that plugins register into | + ### Warnings (carry forward) -- Player lock ordering (`p.mu` before `speaker.Lock()`, goroutine dispatch in beep callback) — do NOT refactor lock-sensitive paths; extract pure logic only +- Player lock ordering (`p.mu` before `speaker.Lock()`, goroutine dispatch in beep callback) — CRITICAL for Phase 12 gapless work - modernc.org/libc version must match exactly when updating modernc.org/sqlite - `@lit-labs/signals` is experimental (v0.2.0) — not blocking but noted +- Tag writing: block edits on currently-playing files (beep holds `*os.File` handle) — Phase 10 +- Scan cancellation: skip orphan cleanup on cancelled scans — Phase 9 +- MusicBrainz: strict 1 req/s rate limit, proper User-Agent, SQLite cache — Phase 13 +- Plugin system: JS-only for v1.1, recover() wrappers, read-only DB access — Phase 14 +- FLAC tag writes load entire file into memory (go-flac) — acceptable for v1.1 — Phase 10 + +### Research Flags + +- **Phase 12 (Gapless + Crossfade):** Needs deeper research — beep Mixer/Seq composition for real-time crossfade not well-documented. Prototype persistent-mixer architecture before committing to implementation. +- **Phase 14 (Plugin System):** Needs deeper research — plugin API surface design, error containment, security boundaries. Consider spike/prototype. ## Session Continuity ### Last Session **Date:** 2026-03-06 -**What happened:** Started milestone v1.1 Features & Extensibility. Updated PROJECT.md with new milestone goals and active requirements. -**Where we stopped:** Defining requirements for v1.1. -**Next action:** Complete requirements definition, create roadmap. +**What happened:** Created v1.1 roadmap with 6 phases (9-14) covering all 43 requirements. Research summary informed phase ordering. Coverage validated at 43/43. +**Where we stopped:** Roadmap created, ready for phase planning. +**Next action:** `/gsd-plan-phase 9` — Plan Scan Cancellation & Keyboard Shortcuts --- *State initialized: 2026-02-27* -Last activity: 2026-03-06 - Milestone v1.1 started +Last activity: 2026-03-06 - v1.1 roadmap created *Last updated: 2026-03-06*