docs: create milestone v1.1 roadmap (6 phases)
This commit is contained in:
+46
-46
@@ -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*
|
||||
|
||||
+93
-1
@@ -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 @@
|
||||
|
||||
</details>
|
||||
|
||||
### 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*
|
||||
|
||||
+50
-11
@@ -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*
|
||||
|
||||
Reference in New Issue
Block a user