- 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)
yonlu