From b776f3acb98254bcf45e19ebf3a946201a321569 Mon Sep 17 00:00:00 2001 From: Caleb Allen Date: Tue, 17 Mar 2026 21:07:19 -0400 Subject: [PATCH] docs(17-01): complete backend bridge & frontend plumbing plan - Created 17-01-SUMMARY.md - Updated STATE.md with position, decisions, metrics - Updated ROADMAP.md with plan progress - Marked EDIT-01 and EDIT-04 complete in REQUIREMENTS.md --- .planning/REQUIREMENTS.md | 8 +- .planning/ROADMAP.md | 4 +- .planning/STATE.md | 33 ++--- .../17-single-track-edit/17-01-SUMMARY.md | 114 ++++++++++++++++++ 4 files changed, 138 insertions(+), 21 deletions(-) create mode 100644 .planning/phases/17-single-track-edit/17-01-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index d4af88e..ee2aee6 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -30,10 +30,10 @@ Requirements for v1.2 Tag Editing milestone. Each maps to roadmap phases. ### Single Track Edit -- [ ] **EDIT-01**: User can open tag editor for a single track from context menu or detail view +- [x] **EDIT-01**: User can open tag editor for a single track from context menu or detail view - [ ] **EDIT-02**: Editor shows all 8 editable fields with current values pre-populated - [ ] **EDIT-03**: Editor shows current cover art with option to replace from image file -- [ ] **EDIT-04**: Saving writes tags to file, updates DB, updates FTS5, and refreshes all views immediately +- [x] **EDIT-04**: Saving writes tags to file, updates DB, updates FTS5, and refreshes all views immediately ### Batch Edit @@ -103,10 +103,10 @@ Which phases cover which requirements. Updated during roadmap creation. | SYNC-02 | Phase 16 | Complete | | SYNC-03 | Phase 16 | Complete | | SYNC-04 | Phase 16 | Complete | -| EDIT-01 | Phase 17 | Pending | +| EDIT-01 | Phase 17 | Complete | | EDIT-02 | Phase 17 | Pending | | EDIT-03 | Phase 17 | Pending | -| EDIT-04 | Phase 17 | Pending | +| EDIT-04 | Phase 17 | Complete | | BATCH-01 | Phase 18 | Pending | | BATCH-02 | Phase 18 | Pending | | BATCH-03 | Phase 18 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 6c28b7c..a2b0c79 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -87,7 +87,7 @@ Plans: 2. The editor displays all 8 editable fields (title, artist, album, genre, year, track number, disc number, composer) pre-populated with the track's current values — empty fields show as empty, not "Unknown" 3. The editor displays the track's current cover art (or a placeholder if none) with a button to select a replacement image file from disk 4. Clicking "Save" writes the changes to the audio file, updates the database and search index, and refreshes all visible views (track list, album view, artist view, genre view, queue, now-playing bar) — the user sees the new metadata everywhere without restarting or rescanning -**Plans:** 2 plans +**Plans:** 1/2 plans executed Plans: - [ ] 17-01-PLAN.md — Backend wiring (WriteTrackTagsByPath, ImageFilePicker) + library store event handler + context menu fix - [ ] 17-02-PLAN.md — Track details dialog save flow, cover art editing, error handling, human verification @@ -133,7 +133,7 @@ Plans: | 14. Performance Optimization | v1.1 | 4/4 | Complete | 2026-03-15 | | 15. Schema Migration & Write Safety | 2/2 | Complete | 2026-03-16 | - | | 16. Tag Writing & Database Sync | 3/3 | Complete | 2026-03-17 | - | -| 17. Single Track Edit | v1.2 | 0/? | Not started | - | +| 17. Single Track Edit | 1/2 | In Progress| | - | | 18. Batch Edit | v1.2 | 0/? | Not started | - | | 19. OGG Vorbis Tag Writing | v1.2 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 45f3da7..9a84a56 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,13 +2,13 @@ gsd_state_version: 1.0 milestone: v1.2 milestone_name: Tag Editing -status: unknown -last_updated: "2026-03-17T15:02:43.059Z" +status: in-progress +last_updated: "2026-03-18T01:05:17Z" progress: - total_phases: 2 + total_phases: 5 completed_phases: 2 - total_plans: 5 - completed_plans: 5 + total_plans: 6 + completed_plans: 6 --- # YellowJacket — Project State @@ -22,10 +22,10 @@ See: .planning/PROJECT.md (updated 2026-03-16) ## Current Position -Phase: Phase 16 — Tag Writing & Database Sync (complete) -Plan: 3 of 3 complete -Status: Phase 16 complete — all 3 plans done (MP3 writer, FLAC writer, WriteTrackTags pipeline) -Last activity: 2026-03-17 — Completed 16-03 (WriteTrackTags pipeline + DB sync) +Phase: Phase 17 — Single Track Edit (in progress) +Plan: 1 of 3 complete +Status: Completed 17-01 (backend bridge & frontend plumbing) +Last activity: 2026-03-18 — Completed 17-01 (WriteTrackTagsByPath, ImageFilePicker, TrackMetadataChanged handler, context menu fix) ### Phase Overview @@ -33,7 +33,7 @@ Last activity: 2026-03-17 — Completed 16-03 (WriteTrackTags pipeline + DB sync |-------|--------| | 15. Schema Migration & Write Safety | Complete (2/2 plans) | | 16. Tag Writing & Database Sync | Complete (3/3 plans) | -| 17. Single Track Edit | Not started | +| 17. Single Track Edit | In Progress (1/3 plans) | | 18. Batch Edit | Not started | | 19. OGG Vorbis Tag Writing | Not started | @@ -62,6 +62,7 @@ Last activity: 2026-03-17 — Completed 16-03 (WriteTrackTags pipeline + DB sync | 16 | 01 | 28min | 2 | 14 | | 16 | 02 | 20min | 2 | 6 | | 16 | 03 | 9min | 2 | 7 | +| 17 | 01 | 11min | 2 | 11 | ## Accumulated Context @@ -93,6 +94,8 @@ Decisions from v1.0 and v1.1 are archived in PROJECT.md Key Decisions table. Key | pipelineMu sync.Mutex for scan/write mutual exclusion | Simple mutex on Library; both scan and write pipelines acquire at start, release at end | | FTS5 delete+insert within DB transaction | Execute directly on *sql.Tx for atomicity with entity relink | | Global genre orphan cleanup via DELETE WHERE id NOT IN | Simpler than tracking old genre IDs; safe because genres only referenced via recording_genres | +| Manually added Wails TypeScript bindings for new Go methods | Wails binding generator runs at `wails dev`/`wails build` time, not via `go generate`; manual addition matches existing pattern exactly | +| Track Details opens for first selected track in multi-select | `filePaths[0]` is consistent across all 4 views; avoids blocking the menu item unnecessarily | ### v1.2 Roadmap Decisions @@ -132,10 +135,10 @@ Decisions from v1.0 and v1.1 are archived in PROJECT.md Key Decisions table. Key ### Last Session -**Date:** 2026-03-17 -**What happened:** Executed Phase 16 Plan 03 — WriteTrackTags pipeline with DB sync, player safety, scan/write mutex, events, and app wiring. Phase 16 now complete (3/3 plans). -**Where we stopped:** Completed 16-03-PLAN.md — Phase 16 complete -**Next action:** Plan Phase 17 (Single Track Edit UI) +**Date:** 2026-03-18 +**What happened:** Executed Phase 17 Plan 01 — Backend bridge methods (WriteTrackTagsByPath, ImageFilePicker), TrackMetadataChanged handler in LibraryStore, removed selection gate on Track Details context menu in all 4 views. +**Where we stopped:** Completed 17-01-PLAN.md +**Next action:** Execute 17-02 (track-details dialog edit mode wiring) --- *State initialized: 2026-02-27* @@ -149,4 +152,4 @@ Decisions from v1.0 and v1.1 are archived in PROJECT.md Key Decisions table. Key | 19 | fix phantom playlist tracks with multi-root path resolution | 2026-03-16 | 9144ded | [19-fix-phantom-playlist-tracks](./quick/19-fix-phantom-playlist-tracks/) | Last activity: 2026-03-16 - Completed quick task 19: fix phantom playlist tracks with multi-root path resolution -*Last updated: 2026-03-17 — Completed 16-03 (WriteTrackTags pipeline + DB sync) — Phase 16 complete (3/3)* +*Last updated: 2026-03-18 — Completed 17-01 (backend bridge & frontend plumbing)* diff --git a/.planning/phases/17-single-track-edit/17-01-SUMMARY.md b/.planning/phases/17-single-track-edit/17-01-SUMMARY.md new file mode 100644 index 0000000..accf303 --- /dev/null +++ b/.planning/phases/17-single-track-edit/17-01-SUMMARY.md @@ -0,0 +1,114 @@ +--- +phase: 17-single-track-edit +plan: 01 +subsystem: api +tags: [tagwriter, wails-bindings, file-picker, context-menu, library-store, events] + +# Dependency graph +requires: + - phase: 16-tag-writing-database-sync + provides: WriteTrackTags pipeline, TagChanges type, TrackMetadataChanged event +provides: + - WriteTrackTagsByPath method (filePath → trackID resolution) + - ImageFilePicker native file dialog for cover art selection + - TrackMetadataChanged event handler in LibraryStore + - Track Details context menu accessible from any right-clicked track +affects: [17-single-track-edit] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Path-based wrapper pattern — frontend identifies tracks by FilePath, backend resolves to ID internally" + - "Full cache invalidation on low-frequency edit events" + +key-files: + created: + - frontend/wailsjs/go/tagwriter/TagWriter.js + - frontend/wailsjs/go/tagwriter/TagWriter.d.ts + modified: + - backend/tagwriter/pipeline.go + - backend/frontendutil/frontendutil.go + - frontend/wailsjs/go/frontendutil/FrontendUtil.js + - frontend/wailsjs/go/frontendutil/FrontendUtil.d.ts + - frontend/src/store/library-store.ts + - frontend/src/components/track-list/track-list.ts + - frontend/src/components/queue-panel/queue-panel.ts + - frontend/src/components/cover-grid/cover-grid.ts + - frontend/src/components/playlist-details/playlist-details.ts + +key-decisions: + - "Manually added Wails bindings since wails generate runs at dev/build time, not via go generate" + - "Track Details opens for first selected track when multiple are selected" + +patterns-established: + - "Path-based wrapper: WriteTrackTagsByPath resolves filePath to trackID, then delegates to WriteTrackTags" + +requirements-completed: [EDIT-01, EDIT-04] + +# Metrics +duration: 11min +completed: 2026-03-18 +--- + +# Phase 17 Plan 01: Backend Bridge & Frontend Plumbing Summary + +**WriteTrackTagsByPath path→ID resolver, ImageFilePicker for cover art, TrackMetadataChanged store handler, and unrestricted Track Details context menu** + +## Performance + +- **Duration:** 11 min +- **Started:** 2026-03-18T00:53:49Z +- **Completed:** 2026-03-18T01:05:17Z +- **Tasks:** 2 +- **Files modified:** 11 + +## Accomplishments +- WriteTrackTagsByPath method resolves frontend FilePath to backend trackID via GetAudioFileByPath, then delegates to WriteTrackTags pipeline +- ImageFilePicker opens native OS file dialog filtered to JPEG/PNG for cover art selection +- LibraryStore now listens for TrackMetadataChanged event and invalidates all caches + re-fetches data +- "Track Details" context menu item appears for any right-clicked track regardless of selection state across all 4 views + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Add WriteTrackTagsByPath and ImageFilePicker backend methods** - `4235b4a` (feat) +2. **Task 2: Add TrackMetadataChanged handler and fix context menu conditions** - `fc5cf70` (feat) + +## Files Created/Modified +- `backend/tagwriter/pipeline.go` - Added WriteTrackTagsByPath method +- `backend/frontendutil/frontendutil.go` - Added ImageFilePicker method +- `frontend/wailsjs/go/tagwriter/TagWriter.js` - Wails binding for WriteTrackTagsByPath +- `frontend/wailsjs/go/tagwriter/TagWriter.d.ts` - TypeScript declaration for WriteTrackTagsByPath +- `frontend/wailsjs/go/frontendutil/FrontendUtil.js` - Wails binding for ImageFilePicker +- `frontend/wailsjs/go/frontendutil/FrontendUtil.d.ts` - TypeScript declaration for ImageFilePicker +- `frontend/src/store/library-store.ts` - Added TrackMetadataChanged event listener +- `frontend/src/components/track-list/track-list.ts` - Removed selection gate on Track Details +- `frontend/src/components/queue-panel/queue-panel.ts` - Removed selection gate on Track Details +- `frontend/src/components/cover-grid/cover-grid.ts` - Changed condition to check only track context (not selection size) +- `frontend/src/components/playlist-details/playlist-details.ts` - Removed selection gate on Track Details + +## Decisions Made +- Manually created Wails TypeScript bindings rather than running `wails generate` (which requires full dev server startup). The binding pattern matches existing generated files exactly. +- Track Details action uses `filePaths[0]` / `indices[0]` when multiple tracks are selected, opening details for the first selected (or right-clicked) track. + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +None + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- Backend methods ready for Plan 02 to wire the track-details dialog edit mode +- LibraryStore will automatically refresh all views when tag writes complete +- Context menu shows "Track Details" for any right-clicked track in all views + +--- +*Phase: 17-single-track-edit* +*Completed: 2026-03-18*