The v3 Songs grid appended every scrolled page and never released nodes,
so card-node count grew unbounded with scroll depth (24 → 624 → 2001 for a
2000-song library). Replace it with a windowed/recycled render: only the
visible window (± overscan) is in the DOM while a #v3-songs-gridsizer
element sized to ceil(total/cols)*rowH gives the scrollbar full-library
geometry; #v3-songs-grid is absolutely positioned to the first visible row.
- state.songs is a sparse, absolutely-indexed store filled a page at a time
by ensureWindow(): the stage-1 keyset cursor for contiguous forward scroll
(O(page)), OFFSET page= for jumps/restore/non-keyset providers. _loadPage
shares an in-flight promise per page and an epoch guard discards a stale
fetch that lands after a reset.
- A–Z rail seeks directly via sort_letters cumulative counts (O(1), no
page-through); bounded scan fallback for legacy providers without it.
- Snapshot/restore is now scrollTop-based (geometry is stable). Select mode,
accuracy badges, ⋮ menu, plugin card actions, and tree/folder coexistence
survive cards recycling; renderWindow re-renders when select mode toggles.
- Plugins get window.v3Songs.visibleCards() + a v3:library-window-rendered
event instead of assuming all cards are present (highway-stutter lesson).
Verified in a browser against a seeded 2001-song library: DOM bounded to
~60 nodes while the count reads "2001 songs", rail jump lands on the target
row, selection survives recycling, scroll-restore exact. Codex-reviewed
(3 findings fixed: stale-fetch epoch guard, await-in-flight page promise,
select-mode resync on cached re-entry).
Frontend-only. Tests: tests/browser/v3-grid-virtualization.spec.ts pins the
bounded-DOM invariant + direct rail jump; tests/js/v3_az_rail.test.js and
v3_songs_scroll.test.js updated to the new wiring.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
