- WriteTrackTagsByPath resolves filePath to trackID via GetAudioFileByPath
- ImageFilePicker opens native file dialog filtered to JPEG/PNG
- Added Wails TypeScript bindings for both new methods
- syncDatabase runs entity relink + FTS5 + orphan cleanup in single tx
- Handles artist, album, genre changes with upsert-and-relink pattern
- FTS5 delete + insert within transaction for search index consistency
- Orphan cleanup for artist_credits, release_groups, and genres
- All hand-crafted SQL has SAFETY comments per codebase convention
- Create 16-01-SUMMARY.md with execution results
- Update STATE.md with Plan 01 progress and decisions
- Update ROADMAP.md plan progress (2/3 plans complete)
- Mark WRITE-01 requirement complete
- Create 16-02-SUMMARY.md with execution results
- Update STATE.md with Phase 16 progress and decisions
- Update ROADMAP.md plan progress
- Mark WRITE-02 and WRITE-04 requirements complete
- SUMMARY.md updated with checkpoint approval and all bugfix commits
- STATE.md updated with Phase 13 completion and new decisions
- ROADMAP.md plan checkboxes and milestone status updated
- REQUIREMENTS.md coverage updated: 31/31 v1.1 requirements complete
- Add ScanHooks callback struct to library package (follows RemovalHooks pattern)
- Move phantom resolution from library to playlist service via hook
- New ResolvePhantomTracksAfterScan reads M3U8 files and resolves paths
against current audio_files using multi-root resolution
- Handles pre-existing phantoms (match by M3U8 position) and new ones
(match by phantom_file_path)
- Delete old resolvePhantomTracks method that required phantom_file_path
- Wire ScanHooks in app.go OnStartup
- Add phantom_file_path column to playlist_tracks (migration 7)
- Store original file_path during RemoveLibrary phantom metadata population
- After each successful scan, UPDATE phantom tracks whose phantom_file_path
now matches an audio_files row, re-linking them and clearing phantom metadata
- Update schema file, sqlc generated code, and database test for new column
- Event delegation handlers were attached in firstUpdated(), but the
virtualizer is conditionally rendered (hidden when tracks empty/loading)
- On first render, tracks are [] so virtualizer doesn't exist, and
firstUpdated() never fires again — delegation was never attached
- Move delegation to a guarded helper called from both firstUpdated()
and updated(), so it attaches as soon as the virtualizer appears
- Fixes click, multi-select, context menu, double-click, and drag in
both track-list and queue-panel components
- GetAllTracksWithFullMetadataByLibrary for tracks filtered by library
- GetAudioFilesByReleaseGroupByLibrary for album tracks in a library
- GetAllAlbumsWithDetailsByLibrary for albums with tracks in a library
- GetAlbumsByArtistByLibrary for artist albums in a library
- GetAlbumArtistsByLibrary for artists with albums in a library
- GetAllGenresWithCountsByLibrary for genre counts within a library
- GetTracksByGenreByLibrary for genre tracks within a library
- Add TestResolveM3UPath with 7 cases: abs, relative, second root, no match, empty roots, nil knownPaths
- Add TestToRelativePathMultiRoot with 5 cases: first root, second root, no root, empty roots, empty string
- Add TestRemoveM3UEntriesMultiRoot: entries from different roots removed correctly
- Add TestFindM3UEntryMultiRoot: entry relative to second root found
- Add TestReplaceM3UEntryPathsMultiRoot: replacement under second root applied
- Replace getLibraryRoot() with getAllLibraryRoots() returning all library paths
- Add resolveM3UPath() for multi-root resolution with knownPaths lookup
- Add toRelativePathMultiRoot() to save relative paths using correct root
- Update removeM3UEntries, replaceM3UEntryPaths, findM3UEntry for []string roots
- Update all 8 call sites in playlist.go for multi-root resolution
- Update existing test signatures for new []string parameter types
- Fix pre-existing golines formatting in scan_queue.go
- Replace wa-icon shadow DOM with inline SVG in queue-panel (xmark)
and album-dropdown (fav icons) to eliminate per-item shadow roots
- Memoize getBeforeEntries/getAfterEntries in cover-grid to prevent
.slice() creating new array refs that trigger virtualizer relayout
- Remove transition: scale and border-radius from album cards to
avoid per-frame repaints and anti-aliased path clipping
- Add queueMicrotask batching to player-store and favorites-store
notify() to coalesce rapid-fire updates into single renders
display:none discards scrollTop in WebKitGTK, so navigating away
from album/artist/genre grids and back reset scroll to top.
Replace inline style.display toggling with a CSS class that uses
visibility:hidden + height:0 + overflow:hidden. This collapses
the element visually while keeping the DOM alive with its scroll
state intact. contain:strict on hidden views ensures zero layout
cost while collapsed.
Targeted optimizations for the DMABuf-disabled rendering path where
every frame is software-composited:
- Replace infinite CSS scroll-text animation with transition-based
cycle that only repaints during active scroll, not during pauses
- Remove CSS mask-image on scrolling text (mask + animation was the
single most expensive continuous repaint)
- Replace wa-icon in track rows with inline SVG — eliminates 30-50
shadow DOM trees (each with SVG fetch/parse) during scroll
- Remove hover transitions on album cards, artist cards, genre cards,
fav icons, queue remove buttons — each transition was causing
per-frame software repaints
- Use visibility:hidden instead of opacity:0 for queue remove button
(binary switch vs per-frame alpha blend)
- Add decoding=async to now-playing cover art images (prevents
main-thread blocking during image decode on track change)
- Add contain:strict to fixed-height track rows (33px) and queue
items (49px) — browser skips size contribution calculations
Instead of disabling DMABuf for all users (hurting AMD/Intel/X11
performance), detect NVIDIA GPU + Wayland session at startup and
only apply WEBKIT_DISABLE_DMABUF_RENDERER=1 for that combo.
Detection checks /proc/driver/nvidia/version first (fast, no
subprocess), falls back to scanning /proc/modules for nvidia.
GPU policy remains Always for everyone — the DMABuf workaround
only affects buffer sharing between WebKitGTK and the display
server, not GPU-accelerated CSS/layout/paint.
Root causes addressed:
- track-list had no _itemSize hint for flow layout — virtualizer
defaulted to 100px, measured actual ~33px rows, then called
_correctScrollError/scrollTo on every scroll causing visible jumps
- will-change:transform on virtualizer elements caused nested GPU
layers (virtualizer positions children with transforms internally)
adding compositor overhead instead of helping
- content-visibility:auto on album cards conflicted with virtualizer's
own DOM recycling, causing redundant layout recalculation
- track-list visibilityChanged handler wrote to store synchronously
on every event (per-item during scroll) without any throttling
- IIFE closure in renderTrackRow created a new function per row per render
Fixes applied:
- Add _itemSize:{height:33} + fixed height:33px on .track-row (matches
queue-panel pattern that already worked smoothly)
- Add overflow-anchor:none on track-list virtualizer
- Remove will-change:transform from all 6 scroll containers
- Remove content-visibility:auto from album cards
- RAF-throttle visibilityChanged scroll position saves
- Replace IIFE with direct cols.map() in template
contain:strict includes size containment which caused a timing issue
where the flex-based main-panel height wasn't resolved before the
virtualizer measured its container, resulting in track-list rendering
at ~20% height on first load until something triggered a relayout.
- Created 14-03-SUMMARY.md with event delegation and store batching results
- Updated STATE.md with plan progress, decisions, and session continuity
- Updated ROADMAP.md with Phase 14 plan progress
- SUMMARY.md with task commits, decisions, and metrics
- STATE.md updated with plan progress and session continuity
- ROADMAP.md updated with Phase 14 plan progress
- Queue store now uses queueMicrotask batching (matching library store pattern)
- Library store adds changeGeneration counter incremented only on actual data changes
- LibraryController checks changeGeneration before requestUpdate, skipping loading-only transitions
- Reduces unnecessary component re-renders during data loading cycles
- Replace inline arrow closures in renderTrackRow with event delegation via data-index
- Replace inline arrow closures in renderTrackItem with event delegation via data-index
- Add delegated click/dblclick/contextmenu/dragstart handlers on virtualizer elements
- Remove button click in queue panel also delegated via closest('.remove-button')
- Zero new function objects created per renderItem call during scroll
- Replace 100ms debounced scroll save in cover grid with requestAnimationFrame throttling
- Position now saves continuously during scrolling (~16ms) instead of only after stop
- Cancel pending RAF in teardown() to prevent leaks
- Add overflow-anchor: none CSS to queue panel lit-virtualizer
- Keep monkey-patch for lit-virtualizer _correctScrollError with expanded comment explaining why CSS alone is insufficient
- SUMMARY.md with 2 tasks, 7 files, 3 min duration
- STATE.md updated with plan position, metrics, decisions
- ROADMAP.md updated with plan progress (2/4)
- Created 14-02-SUMMARY.md with execution results
- Updated STATE.md with Phase 14 position and decisions
- Updated ROADMAP.md progress for Phase 14 (1/4 plans)
- contain: layout style on :host of all 6 scroll-heavy components
- contain: paint + will-change: transform on all scroll containers for GPU compositing
- content-visibility: auto + contain-intrinsic-size on .album-card for off-screen skip
- cover-grid, track-list, queue-panel, artists-view, genres-view, playlist-view
- Primary views (tracks, albums, artists, genres, playlists, settings) created once and kept in DOM
- Navigation toggles display:none/display:'' instead of destroying/recreating components
- viewCache Map bounded to 6 entries — no memory leaks
- Detail views (artist-details, playlist-details, genre-details) remain ephemeral
- Scroll positions naturally preserved by keeping DOM alive
- No virtualizer reinit, no data refetch, no image reload on navigation
- contain: layout style on .content-area to isolate main+queue from header/sidebar
- contain: strict on .main-panel for maximum layout isolation
- contain: layout style paint on .main-panel > * for paint containment per view
- contain: layout style paint on sidebar to isolate from main panel
- contain: layout style on .bottom-bar to isolate footer from content reflows
Sections start collapsed showing only heading, description, and a
chevron icon. Click to expand and reveal the fields. The open property
allows sections to start expanded if needed.
Progress bar now renders below the library row being scanned, with
a small status label (phase + percent) after the library name. Removed
the separate status-bar progress display.
Add Library now sits in the same row as Scan and Full Rescan, sharing
the same btn-primary style and size. Removed the standalone button
below the library list.
Scan and Full Rescan buttons now sit above the library list for easier
access. Libraries start unchecked — both buttons are disabled until at
least one library is selected.
Go's error interface has no exported fields, so json.Marshal produced
{} for the error message. Converting to string at the addWarning call
site preserves the actual error text in the JSON payload.
Contentless FTS5 cannot delete individual rows, but stale entries are
filtered out by the JOIN against track_metadata in search queries.
The index is rebuilt on the next full rescan. Removes ~10s of overhead
for a 25K-track library removal.
artist_credit_artist.credit_id references artist_credit.id, so the
child table must be cleaned before the parent. Same FK ordering fix
as the earlier recording_genres/recordings swap.
getLibraryRoot() returned "" after DirectoryPath was removed from
config.toml during multi-library migration. M3U8 relative paths could
not be resolved to absolute paths, causing every playlist track to
appear as phantom. Now falls back to the first library path from the
database when the legacy config field is empty.
Tracks from the pre-multi-library schema have library_id=0 and aren't
counted by CountAudioFilesByLibrary, causing a permanent count mismatch
that triggers a full scan on every launch. SoftScanAllLibraries now
claims matching orphans before comparing counts.
SoftScanAllLibraries compares audio file count on disk vs DB track count
per library. Unchanged libraries are silently skipped (no progress bar,
no events). Only libraries where files were added or removed since the
last scan get queued for a full scan.
recording_genres and release_group_recordings reference recordings.id,
so they must be deleted BEFORE the recordings table is cleaned.
Also extends toast duration to 8s for readability.
RemoveLibrary now polls until the cancelled scan goroutine finishes
before proceeding with the removal transaction. Also show removal
errors as toast messages instead of only logging to console, and
explicitly reload library list after successful removal.
Tracks from pre-multi-library schema have library_id=0 (default).
When AddLibrary creates a new library row, UPDATE orphaned tracks
whose file_path falls under the library's directory to use the new
library_id. This prevents the scan from hitting UNIQUE constraints
on every file and ensures track counts are correct immediately.
- Add checkboxes to library list with select-all header
- Soft Scan operates on selected libraries (queues each individually)
- Full Rescan stays global (nukes all data, rescans all libraries)
- Remove redundant 'Scan All Libraries' button
- Fix FullRescan Go backend to scan all libraries after wipe, not just first
Files that fail to save (e.g. UNIQUE constraint from pre-existing
tracks with a different library_id) were not counted in any progress
counter, leaving the progress bar stuck at 0%. Now increments skipped
so processed = added + skipped + updated reflects all files visited.
Scan() wrapper was deleted in Phase 11 but config-page.ts and
library-manager.ts still imported it. Use ScanAllLibraries() for
soft scan since multi-library model scans all libraries.
- Remove 'libraries' from View type union in app-sidebar.ts
- Remove Libraries nav item from sidebar navigation list
- Remove case 'libraries' view routing in index.ts
- Remove library-manager component import from index.ts
- Add CompactAfterLibraryRemoval on Queue: reloads surviving tracks from DB, resets currentIndex, unloads player if current track was removed, clears shuffle order
- Wire RemovalHooks in app.go OnStartup: StopPlayback → player.UnloadTrack, CompactQueue → queue.CompactAfterLibraryRemoval
- All existing tests pass with no regressions
yonlu