' +
'
';
}
@@ -796,8 +834,23 @@
const items = (reg ? reg.list(song) : []).filter((a) => !a.placement || a.placement === 'menu');
const menu = document.createElement('div');
menu.className = 'v3-card-menu absolute top-10 right-2 z-30 min-w-[10rem] bg-fb-card border border-fb-border/60 rounded-lg shadow-xl py-1 text-sm';
+ // Multi-chart entries (P5d): a grouped grid row carries chart_count +
+ // work_key (P5a annotation), so the menu knows inline whether this card
+ // stands for versions. Local library only — the work API is local.
+ const canCharts = state.provider === 'local' && song.work_key && song.chart_count >= 2;
+ // Play follows the DISPLAYED chart (see wireCards) — under an intrinsic
+ // filter that's the matching member, not the representative.
+ const playTarget = song.display_chart ? Object.assign({}, song, song.display_chart) : song;
const rows = [
- { id: '__play', label: 'Play', run: () => { _saveLibraryScrollSnapshot(); window.playSong && window.playSong(enc(song.filename)); } },
+ { id: '__play', label: 'Play', run: () => { _saveLibraryScrollSnapshot(); window.playSong && window.playSong(enc(playTarget.filename)); } },
+ ...(canCharts ? [
+ { id: '__charts', label: 'Charts (' + song.chart_count + ')…' },
+ { id: '__playver', label: 'Play version ▸' },
+ ] : []),
+ // Undo for the drawer's "Split out" (P5e) — a split chart is its
+ // own singleton card (no ⚑ chip), so this is its only way back.
+ ...(state.provider === 'local' && song.is_split
+ ? [{ id: '__unsplit', label: 'Rejoin other versions' }] : []),
{ id: '__playlist', label: 'Add to playlist' },
...items.map((a) => ({ id: a.id, label: a.label, destructive: a.destructive, enabled: a.enabled, plugin: a.pluginId })),
];
@@ -816,30 +869,308 @@
menu.querySelectorAll('[data-act]').forEach((b) => b.addEventListener('click', async (e) => {
e.stopPropagation();
const id = b.getAttribute('data-act');
+ // 'Play version ▸' swaps THIS menu's rows for the work's charts —
+ // it must expand in place, so it's the one entry that doesn't close.
+ if (id === '__playver') { await _expandPlayVersions(menu, song, closeMenu); return; }
closeMenu();
- if (id === '__play') { playCard(song); return; }
+ if (id === '__play') { playCard(playTarget); return; }
+ if (id === '__charts') { openChartsDrawer(song.work_key, song); return; }
+ if (id === '__unsplit') {
+ if (await jsend('POST', '/api/chart/' + enc(song.filename) + '/unsplit')) _groupChanged();
+ return;
+ }
if (id === '__playlist') { await addFilenamesToPlaylist([song.filename]); return; }
if (reg) await reg.run(id, song, { source: 'v3-songs' });
}));
+ // Tree rows ride the (ungrouped) artists endpoint, so they don't carry
+ // chart_count/work_key — resolve the work lazily and slot a
+ // "Charts (N)…" entry into the still-open menu when versions exist.
+ // Grid rows already carry both (chart_count defined ⇒ no fetch).
+ if (state.provider === 'local' && song.chart_count === undefined && song.filename) {
+ jget('/api/chart/' + enc(song.filename) + '/work').then((w) => {
+ if (!w || !menu.isConnected) return;
+ const addEntry = (label, run) => {
+ const b = document.createElement('button');
+ b.className = 'w-full text-left px-3 py-1.5 hover:bg-fb-card/60 text-fb-text';
+ b.textContent = label;
+ b.addEventListener('click', (e) => { e.stopPropagation(); closeMenu(); run(); });
+ menu.appendChild(b);
+ };
+ if (w.chart_count >= 2 && w.work_key) {
+ addEntry('Charts (' + w.chart_count + ')…', () => openChartsDrawer(w.work_key, song));
+ }
+ if (w.is_split) {
+ addEntry('Rejoin other versions', async () => {
+ if (await jsend('POST', '/api/chart/' + enc(song.filename) + '/unsplit')) _groupChanged();
+ });
+ }
+ });
+ }
setTimeout(() => document.addEventListener('click', closer), 0);
}
+ // 'Play version ▸' (P5d): swap the ⋮ menu's rows for the work's charts;
+ // picking one plays that chart directly. A one-off alternate play — the
+ // keeper/headline doesn't move (stats record to the played chart's own
+ // filename), which is the design's "casual try ≠ deliberate adopt".
+ async function _expandPlayVersions(menu, song, closeMenu) {
+ const data = await jget('/api/work/' + enc(song.work_key) + '/charts');
+ if (!data || !Array.isArray(data.charts) || !data.charts.length || !menu.isConnected) return;
+ menu.innerHTML = data.charts.map((c) => {
+ const tl = (typeof window.displayTuningName === 'function')
+ ? window.displayTuningName(c.tuning_name || c.tuning) : (c.tuning_name || '');
+ return '';
+ }).join('');
+ menu.querySelectorAll('[data-ver]').forEach((vb) => vb.addEventListener('click', (e) => {
+ e.stopPropagation();
+ const fn = vb.getAttribute('data-ver');
+ closeMenu();
+ _saveLibraryScrollSnapshot();
+ if (window.playSong) window.playSong(enc(fn));
+ }));
+ }
+
+ // ── Charts drawer (P5d, design §7.1 UX-2/3) ────────────────────────────────
+ // The single deep-management surface for a work's charts. A body-appended
+ // slide-in panel (the filter-drawer idiom; body-appended like the playlist
+ // picker so it opens from any view) listing every chart of the work as a
+ // radiogroup — the checked row is the keeper the grid card plays. Clicking
+ // an unchecked row (or Enter/Space on it) = Set as preferred, one tap;
+ // "Reset to auto pick" appears when the keeper is your explicit pick.
+ // Writes go through the work-charts API and the drawer re-renders from the
+ // response (there's no server-side library event bus — the drawer is its
+ // own refresh); the grid re-fetches because the representative may have
+ // flipped. Global mode only — the slot-scoped (curated-album) mode is P6;
+ // the per-row Split escape hatch is P5e.
+ let _chartsPrevFocus = null; // focus to restore when the drawer closes
+
+ function _chartsDrawerEls() {
+ let ov = document.getElementById('v3-charts-overlay');
+ let dr = document.getElementById('v3-charts-drawer');
+ if (!ov) {
+ ov = document.createElement('div');
+ ov.id = 'v3-charts-overlay';
+ ov.className = 'fixed inset-0 bg-black/50 z-40 hidden';
+ ov.addEventListener('click', closeChartsDrawer);
+ document.body.appendChild(ov);
+ }
+ if (!dr) {
+ dr = document.createElement('aside');
+ dr.id = 'v3-charts-drawer';
+ dr.className = 'fixed top-0 right-0 h-full w-full sm:w-96 bg-fb-sidebar border-l border-fb-border/50 z-50 transform translate-x-full transition-transform duration-200 overflow-y-auto v3-scroll';
+ dr.setAttribute('role', 'dialog');
+ dr.setAttribute('aria-modal', 'true');
+ dr.setAttribute('aria-label', 'Charts of this song');
+ // a11y: Escape closes; Tab is trapped inside the open drawer
+ // (aria-modal alone doesn't trap for keyboard users); ArrowUp/Down
+ // move focus between the chart rows (focus only — selection stays
+ // on Enter/Space, since a native-radio "arrow = select" would fire
+ // a preferred write on every keystroke).
+ dr.addEventListener('keydown', (e) => {
+ if (e.key === 'Escape') { e.preventDefault(); closeChartsDrawer(); return; }
+ if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+ const rows = [...dr.querySelectorAll('[role="radio"]')];
+ if (!rows.length) return;
+ const i = rows.indexOf(document.activeElement);
+ if (i === -1) return;
+ e.preventDefault();
+ rows[(i + (e.key === 'ArrowDown' ? 1 : rows.length - 1)) % rows.length].focus();
+ return;
+ }
+ if (e.key !== 'Tab') return;
+ const foci = dr.querySelectorAll('button, [tabindex]:not([tabindex="-1"])');
+ if (!foci.length) return;
+ const first = foci[0], last = foci[foci.length - 1];
+ if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+ else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+ });
+ document.body.appendChild(dr);
+ }
+ return { ov: ov, dr: dr };
+ }
+
+ // One chart row. `checked` = the current keeper (pref or auto-pick). The
+ // filename line is deliberate: duplicate charts usually share title/artist,
+ // so the pack filename is often the only human-readable distinguisher.
+ function _chartRowHtml(c, data) {
+ const checked = c.is_representative;
+ const prefLabel = checked
+ ? (data.preferred_source === 'user' ? 'Preferred — your pick' : 'Preferred (auto)')
+ : '';
+ const tuningLabel = (typeof window.displayTuningName === 'function')
+ ? window.displayTuningName(c.tuning_name || c.tuning)
+ : (c.tuning_name || '');
+ const meta = [fmtLabel(c), tuningLabel,
+ (c.arrangements || []).map((a) => a.name).join('/'),
+ c.year ? String(c.year) : '']
+ .filter(Boolean).join(' · ');
+ const acc = (typeof c.best_accuracy === 'number')
+ ? '' + Math.round(c.best_accuracy * 100) + '%'
+ : 'not played';
+ return '' +
- ') + ')
' +
- tuning + checkbox + accuracyBadge(key) + fmtBadge(song) + personalBadges(song) + overlay +
+ ') + ')
' +
+ tuning + checkbox + accuracyBadge(key) + fmtBadge(shown) + personalBadges(song) + overlay +
'
' +
- '' +
inlineBtns +
'' +
'' +
'' +
'
' + esc(song.title) + '
' +
+ '' + esc(shown.title) + '
' +
'' + esc(song.artist) + '
' +
// Always emit the chip row (even when empty) at a FIXED single-line
// height — uniform card height is what makes the windowed grid's
// absolute-position math exact (.v3-card-chips in v3.css).
- '' + arrChips + '
' +
+ '' + chartsChip + arrChips + '
' +
'' +
+ '
';
+ }
+
+ // A preferred/auto flip can change which chart the grid's card stands for —
+ // re-fetch the grid in place (scroll preserved; renderWindow refills from
+ // the current scrollTop). The tree lists every chart flat, so it's
+ // unaffected; rare curate action, so a full re-fetch is fine.
+ function _groupChanged() {
+ if (state.view === 'grid' && groupingActive()) loadGrid(true);
+ }
+
+ function _renderChartsDrawer(data, opts) {
+ const els = _chartsDrawerEls();
+ const dr = els.dr;
+ const head = data.charts.find((c) => c.is_representative) || data.charts[0];
+ // Mastery-anchor heads-up (§7.1): shown once, ambiently, right after a
+ // switch — the headline may drop because history stays with each chart
+ // (motor mastery is arrangement-specific). Text only, no toast/sound.
+ const switchNote = (opts && opts.switched)
+ ? '' +
+ '
' +
+ '' +
+ '
' +
+ '' +
+ '' + esc(c.title) + '
' +
+ '' + esc(meta) + ' · ' + acc + '
' +
+ '' + esc(c.filename) + '
' +
+ (prefLabel ? '' + esc(prefLabel) + '
' : '') +
+ '' +
+ '' +
+ // Split escape hatch (P5e, §7.1): "these aren't the same song".
+ // Only offered while the work still has 2+ charts — splitting the
+ // last member is meaningless. Undo lives in the split-out card's
+ // ⋮ menu ("Rejoin other versions").
+ (data.count >= 2
+ ? ''
+ : '') +
+ '
' +
+ 'Practice history stays with each chart — your new pick starts from its own stats.
'
+ : '';
+ dr.innerHTML =
+ '' +
+ '
';
+
+ dr.querySelector('[data-charts-close]').addEventListener('click', closeChartsDrawer);
+ dr.querySelector('[data-charts-auto]')?.addEventListener('click', async () => {
+ const fresh = await jsend('DELETE', '/api/work/' + enc(data.work_key) + '/preferred');
+ if (!fresh) return;
+ _renderChartsDrawer(fresh);
+ _groupChanged();
+ dr.querySelector('[role="radio"][aria-checked="true"]')?.focus();
+ });
+ dr.querySelectorAll('[data-ch]').forEach((row) => {
+ const fn = row.getAttribute('data-ch');
+ const setPreferred = async () => {
+ if (row.getAttribute('aria-checked') === 'true') return; // already the keeper
+ const fresh = await jsend('PUT', '/api/work/' + enc(data.work_key) + '/preferred', { filename: fn });
+ if (!fresh) return;
+ _renderChartsDrawer(fresh, { switched: true });
+ _groupChanged();
+ dr.querySelector('[role="radio"][aria-checked="true"]')?.focus();
+ };
+ row.addEventListener('click', setPreferred);
+ row.addEventListener('keydown', (e) => {
+ if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setPreferred(); }
+ });
+ row.querySelector('[data-ch-play]')?.addEventListener('click', (e) => {
+ e.stopPropagation();
+ closeChartsDrawer();
+ _saveLibraryScrollSnapshot();
+ if (window.playSong) window.playSong(enc(fn));
+ });
+ row.querySelector('[data-ch-pl]')?.addEventListener('click', (e) => {
+ e.stopPropagation();
+ addFilenamesToPlaylist([fn]);
+ });
+ row.querySelector('[data-ch-split]')?.addEventListener('click', async (e) => {
+ e.stopPropagation();
+ const ok = await jsend('POST', '/api/chart/' + enc(fn) + '/split');
+ if (!ok) return;
+ _groupChanged();
+ // Re-read the ORIGINAL work — the split chart is gone from it
+ // (now its own card in the grid; its ⋮ menu offers the rejoin).
+ const fresh = await jget('/api/work/' + enc(data.work_key) + '/charts');
+ if (fresh && Array.isArray(fresh.charts) && fresh.charts.length) _renderChartsDrawer(fresh);
+ else closeChartsDrawer();
+ });
+ });
+ }
+
+ async function openChartsDrawer(workKey, _song) {
+ if (!workKey) return;
+ const data = await jget('/api/work/' + enc(workKey) + '/charts');
+ if (!data || !Array.isArray(data.charts) || !data.charts.length) return;
+ const els = _chartsDrawerEls();
+ _chartsPrevFocus = document.activeElement;
+ _renderChartsDrawer(data);
+ els.ov.classList.remove('hidden');
+ els.dr.classList.remove('translate-x-full');
+ els.dr.querySelector('[role="radio"][aria-checked="true"]')?.focus();
+ }
+
+ function closeChartsDrawer() {
+ document.getElementById('v3-charts-overlay')?.classList.add('hidden');
+ document.getElementById('v3-charts-drawer')?.classList.add('translate-x-full');
+ if (_chartsPrevFocus && typeof _chartsPrevFocus.focus === 'function' && _chartsPrevFocus.isConnected) {
+ _chartsPrevFocus.focus();
+ }
+ _chartsPrevFocus = null;
+ }
+
+ // Global opener — the ⚑ chip routes through this, and other views/plugins
+ // (P2's details drawer, dashboards) can open the drawer without reaching
+ // into this module.
+ window.__fbOpenChartsDrawer = openChartsDrawer;
+
function wireCards(scope) {
scope.querySelectorAll('[data-fn]').forEach((el) => {
if (el.dataset.wired) return; // don't double-bind on append/auto-fill
el.dataset.wired = '1';
const fn = el.getAttribute('data-fn');
const song = state.songsById[fn] || { filename: fn };
+ // §7.1: when a chart-intrinsic filter attached a display_chart,
+ // the card SHOWS that member — so play actions target it too
+ // (its arrangement indices match the rendered chips). Identity
+ // actions (heart/save/playlist/menu registry) stay on the rep row.
+ const playTarget = song.display_chart ? Object.assign({}, song, song.display_chart) : song;
el.querySelectorAll('[data-v3-play]').forEach((pe) => pe.addEventListener('click', (e) => {
if (state.selectMode) { e.preventDefault(); toggleSelect(fn, el); return; }
- playCard(song); // local → play; unsynced remote → sync then play
+ playCard(playTarget); // local → play; unsynced remote → sync then play
}));
el.querySelector('[data-menu]')?.addEventListener('click', (e) => { e.stopPropagation(); openCardMenu(el, song, e.currentTarget); });
el.querySelectorAll('[data-arr]').forEach((ab) => ab.addEventListener('click', (e) => {
e.stopPropagation();
const idx = ab.getAttribute('data-arr');
- playCard(song, idx === '' ? undefined : Number(idx));
+ playCard(playTarget, idx === '' ? undefined : Number(idx));
}));
+ // ⚑ charts chip → the Charts drawer (P5d). Never a card play — the
+ // chip row sits outside [data-v3-play]; stopPropagation is
+ // belt-and-braces.
+ el.querySelector('[data-charts]')?.addEventListener('click', (e) => {
+ e.stopPropagation();
+ openChartsDrawer(e.currentTarget.getAttribute('data-charts'), song);
+ });
el.querySelector('[data-fav]')?.addEventListener('click', async (e) => {
e.stopPropagation();
const btn = e.currentTarget;
@@ -1234,6 +1565,7 @@
const epoch = state.epoch;
const prom = (async () => {
const extra = { size: PAGE_SIZE };
+ if (groupingActive()) extra.group = 1;
const prevCursor = state.keysetOk ? state.pageCursors[p - 1] : null;
if (prevCursor) extra.after = prevCursor; else extra.page = p;
const data = await jget('/api/library?' + queryParams(extra).toString());
@@ -1414,7 +1746,11 @@
// Present letters for the active sort+filter (filter-synced; counts
// songs). `sort_letters=1` opts into the active-sort breakdown so the
// dashboard / v2 tree (which read only `letters`) skip the extra query.
- const stats = await jget('/api/library/stats?' + queryParams({ sort_letters: 1 }).toString());
+ // group must MATCH the grid's page fetches (see groupingActive) so the
+ // rail's per-letter counts sum to the same works total the sizer uses.
+ const railParams = { sort_letters: 1 };
+ if (groupingActive()) railParams.group = 1;
+ const stats = await jget('/api/library/stats?' + queryParams(railParams).toString());
if (_railToken !== myToken || !railVisible()) { // changed mid-fetch
if (_railToken === myToken) rail.classList.add('hidden');
return;
@@ -1708,6 +2044,15 @@
}
return triPill('tuning', val, label + ' (' + t.count + ')', f.tunings.includes(val) ? 'has' : 'any');
}).join('') || 'No tunings') +
+ // Multi-chart grouping toggle (P5e) — a VIEW mode, not a filter
+ // (never counted in the badge, never saved into collection rules).
+ // Local provider only: it's the one that implements group=.
+ (state.provider === 'local'
+ ? section('Grouping', '')
+ : '') +
// Collections always replay against the LOCAL library, so only offer
// "save" when browsing local with a non-empty filter set.
(state.provider === 'local' && Object.keys(currentFilterRules()).length
@@ -1730,6 +2075,11 @@
}));
d.querySelectorAll('[data-lyrics]').forEach((b) => b.addEventListener('click', () => { f.lyrics = b.getAttribute('data-lyrics'); renderDrawer(); }));
d.querySelectorAll('[data-mastery]').forEach((b) => b.addEventListener('click', () => { const v = b.getAttribute('data-mastery'); const i = f.mastery.indexOf(v); if (i >= 0) f.mastery.splice(i, 1); else f.mastery.push(v); renderDrawer(); }));
+ d.querySelector('[data-grouping]')?.addEventListener('click', () => {
+ state.grouping = !(state.grouping !== false);
+ renderDrawer();
+ reload(); // re-fetches grid + rail with/without group=1, saves prefs
+ });
d.querySelector('[data-drawer-save]')?.addEventListener('click', saveCurrentAsCollection);
d.querySelector('[data-drawer-tidy]')?.addEventListener('click', openArtistTidyUp);
d.querySelector('[data-drawer-close]')?.addEventListener('click', closeDrawer);
diff --git a/tests/test_group_filter_law.py b/tests/test_group_filter_law.py
new file mode 100644
index 0000000..072c660
--- /dev/null
+++ b/tests/test_group_filter_law.py
@@ -0,0 +1,198 @@
+"""Tests for P5e: the grouped filter law (chart-intrinsic filters match ANY
+member of a work + the display_chart switch), the group-aggregate mastery
+sort, the history-sticky auto-pick, and the split annotations."""
+
+import importlib
+import sys
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture()
+def server(tmp_path, monkeypatch, isolate_logging):
+ monkeypatch.setenv("CONFIG_DIR", str(tmp_path))
+ monkeypatch.setenv("FEEDBACK_SKIP_STARTUP_TASKS", "1")
+ sys.modules.pop("server", None)
+ srv = importlib.import_module("server")
+ try:
+ yield srv
+ finally:
+ conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+ if conn is not None:
+ conn.close()
+ sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+ return TestClient(server.app)
+
+
+def _put(server, fn, title, artist, arrangements=1, tuning="E Standard",
+ mtime=0, lyrics=False):
+ arr = [{"name": "Lead", "index": i} for i in range(arrangements)]
+ server.meta_db.put(fn, mtime, 0, {
+ "title": title, "artist": artist, "arrangements": arr,
+ "tuning_name": tuning, "has_lyrics": lyrics,
+ })
+
+
+def _page(client, **params):
+ return client.get("/api/library", params={"group": 1, **params}).json()
+
+
+# ── chart-intrinsic filters: match if ANY member matches ─────────────────────
+
+def test_intrinsic_filter_matches_any_member(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2, tuning="E Standard")
+ _put(server, "b.archive", "Song", "Artist", arrangements=1, tuning="Drop D")
+ body = _page(client, tunings="Drop D")
+ # the work qualifies through member b even though the representative (a,
+ # most arrangements) is E Standard…
+ assert body["total"] == 1
+ row = body["songs"][0]
+ # …and the ROW stays the representative (sort/cursor identity) while the
+ # card's display/play facts switch to the matching member.
+ assert row["filename"] == "a.archive"
+ assert row["display_chart"]["filename"] == "b.archive"
+ assert row["display_chart"]["tuning_name"] == "Drop D"
+
+
+def test_no_display_chart_when_rep_matches(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2, tuning="Drop D")
+ _put(server, "b.archive", "Song", "Artist", arrangements=1, tuning="Drop D")
+ row = _page(client, tunings="Drop D")["songs"][0]
+ assert row["filename"] == "a.archive"
+ assert "display_chart" not in row
+
+
+def test_intrinsic_filter_ungrouped_unchanged(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2, tuning="E Standard")
+ _put(server, "b.archive", "Song", "Artist", arrangements=1, tuning="Drop D")
+ body = client.get("/api/library", params={"tunings": "Drop D"}).json()
+ assert body["total"] == 1
+ assert body["songs"][0]["filename"] == "b.archive"
+ assert "display_chart" not in body["songs"][0]
+
+
+def test_lyrics_filter_matches_any_member(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2, lyrics=False)
+ _put(server, "b.archive", "Song", "Artist", arrangements=1, lyrics=True)
+ body = _page(client, has_lyrics=1)
+ assert body["total"] == 1
+ assert body["songs"][0]["display_chart"]["filename"] == "b.archive"
+
+
+def test_stats_count_matches_page_under_filter(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2, tuning="E Standard")
+ _put(server, "b.archive", "Song", "Artist", arrangements=1, tuning="Drop D")
+ _put(server, "c.archive", "Other", "Artist", tuning="E Standard") # no Drop D chart
+ page = _page(client, tunings="Drop D")
+ stats = client.get("/api/library/stats",
+ params={"group": 1, "tunings": "Drop D"}).json()
+ assert page["total"] == 1
+ assert stats["total_songs"] == page["total"]
+
+
+# ── work-identity + practice-state stay on the representative ────────────────
+
+def test_practice_state_anchors_on_preferred(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2) # unplayed
+ _put(server, "b.archive", "Song", "Artist", arrangements=1)
+ server.meta_db.record_session("b.archive", 0, score=950, accuracy=0.95)
+ # pin the unplayed chart as YOUR pick (without a pin the played chart is
+ # the sticky auto-rep, so the anchor would legitimately read mastered)
+ wk = server.meta_db.work_key_for("a.archive")
+ server.meta_db.set_chart_preferred(wk, "a.archive")
+ # mastered band reads the PREFERRED chart (unplayed) — the work is not
+ # "mastered" just because an alternate chart is (§7.1 practice-state law)
+ assert _page(client, mastery="mastered")["total"] == 0
+ # …but the flat view still finds the mastered chart itself
+ flat = client.get("/api/library", params={"mastery": "mastered"}).json()
+ assert [s["filename"] for s in flat["songs"]] == ["b.archive"]
+
+
+# ── mastery sort aggregates MAX across the group ─────────────────────────────
+
+def test_mastery_sort_aggregates_across_group(client, server):
+ _put(server, "a1.archive", "One", "Artist", arrangements=2)
+ _put(server, "a2.archive", "One", "Artist", arrangements=1)
+ _put(server, "b.archive", "Two", "Artist") # singleton work 2
+ server.meta_db.record_session("a2.archive", 0, score=950, accuracy=0.95)
+ server.meta_db.record_session("b.archive", 0, score=500, accuracy=0.5)
+ # pin the UNPLAYED chart as work 1's keeper — the aggregate must still
+ # surface the work via its touched member ("a song surfaces on any chart
+ # you've touched"), even though the preferred chart has no stats
+ wk = server.meta_db.work_key_for("a1.archive")
+ server.meta_db.set_chart_preferred(wk, "a1.archive")
+ desc = [s["filename"] for s in _page(client, sort="mastery-desc")["songs"]]
+ assert desc == ["a1.archive", "b.archive"] # 0.95 > 0.5, row = keeper
+ asc = [s["filename"] for s in _page(client, sort="mastery")["songs"]]
+ assert asc == ["b.archive", "a1.archive"]
+
+
+# ── history-sticky auto-pick ──────────────────────────────────────────────────
+
+def test_autopick_sticks_with_played_chart(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=1, mtime=1)
+ server.meta_db.record_session("a.archive", 0, score=500, accuracy=0.5)
+ # a newer, more complete chart imports — the pick must NOT silently migrate
+ _put(server, "b.archive", "Song", "Artist", arrangements=3, mtime=2)
+ assert _page(client)["songs"][0]["filename"] == "a.archive"
+
+
+def test_autopick_completeness_still_wins_when_unplayed(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=1, mtime=1)
+ _put(server, "b.archive", "Song", "Artist", arrangements=3, mtime=2)
+ assert _page(client)["songs"][0]["filename"] == "b.archive"
+
+
+def test_autopick_one_off_try_does_not_steal_pick(client, server):
+ # incumbent: practiced repeatedly, minimal chart; a one-off try of a more
+ # complete alternate must NOT retarget the pick (casual try ≠ adopt)
+ _put(server, "a.archive", "Song", "Artist", arrangements=1, mtime=1)
+ for _ in range(3):
+ server.meta_db.record_session("a.archive", 0, score=500, accuracy=0.5)
+ _put(server, "b.archive", "Song", "Artist", arrangements=3, mtime=2)
+ server.meta_db.record_session("b.archive", 0, score=500, accuracy=0.5)
+ assert _page(client)["songs"][0]["filename"] == "a.archive"
+
+
+# ── split annotations (the ⋮ "Rejoin other versions" undo) ───────────────────
+
+def test_split_flags_on_rows_and_chart_work(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "b.archive", "Song", "Artist")
+ client.post("/api/chart/b.archive/split")
+ rows = {s["filename"]: s for s in _page(client)["songs"]}
+ assert rows["b.archive"]["is_split"] is True
+ assert rows["a.archive"]["is_split"] is False
+ assert client.get("/api/chart/b.archive/work").json()["is_split"] is True
+ assert client.get("/api/chart/a.archive/work").json()["is_split"] is False
+
+
+# ── keyset paging stays exact under the member-match predicate ────────────────
+
+def test_grouped_keyset_pagination_with_intrinsic_filter(client, server):
+ # 5 works; each has an E-Standard rep (2 arrangements) + a Drop-D member,
+ # so the Drop-D filter admits every work through a NON-representative chart.
+ for i in range(5):
+ _put(server, f"w{i}rep.archive", f"Song {i}", f"Artist {i}",
+ arrangements=2, tuning="E Standard")
+ _put(server, f"w{i}alt.archive", f"Song {i}", f"Artist {i}",
+ arrangements=1, tuning="Drop D")
+ seen, cursor = [], None
+ for _ in range(10):
+ params = {"group": 1, "tunings": "Drop D", "size": 2, "sort": "artist"}
+ if cursor:
+ params["after"] = cursor
+ body = client.get("/api/library", params=params).json()
+ if not body["songs"]:
+ break
+ seen += [s["filename"] for s in body["songs"]]
+ cursor = body["next_cursor"]
+ if not cursor:
+ break
+ assert seen == [f"w{i}rep.archive" for i in range(5)] # no skip, no dupe
+ assert all(s.startswith("w") and "rep" in s for s in seen)
diff --git a/tests/test_work_charts_api.py b/tests/test_work_charts_api.py
new file mode 100644
index 0000000..51e5102
--- /dev/null
+++ b/tests/test_work_charts_api.py
@@ -0,0 +1,164 @@
+"""Tests for the multi-chart work API (P5b): GET /api/work/{work_key}/charts +
+PUT/DELETE …/preferred + POST /api/chart/{filename}/split|unsplit. HTTP surface
+over the P5a grouping engine (what the P5d Charts drawer consumes)."""
+
+import importlib
+import sys
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture()
+def server(tmp_path, monkeypatch, isolate_logging):
+ monkeypatch.setenv("CONFIG_DIR", str(tmp_path))
+ monkeypatch.setenv("FEEDBACK_SKIP_STARTUP_TASKS", "1")
+ sys.modules.pop("server", None)
+ srv = importlib.import_module("server")
+ try:
+ yield srv
+ finally:
+ conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+ if conn is not None:
+ conn.close()
+ sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+ return TestClient(server.app)
+
+
+def _put(server, fn, title, artist, arrangements=1):
+ arr = [{"name": "Lead", "index": i} for i in range(arrangements)]
+ server.meta_db.put(fn, 0, 0, {"title": title, "artist": artist, "arrangements": arr})
+
+
+def _wk(server, fn):
+ return server.meta_db.work_key_for(fn)
+
+
+def _rep(body):
+ return next(c for c in body["charts"] if c["is_representative"])
+
+
+# ── grouped grid row carries work_key (so the drawer can address it) ─────────
+
+def test_grouped_row_exposes_work_key(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "b.archive", "Song", "Artist")
+ row = client.get("/api/library", params={"group": 1}).json()["songs"][0]
+ assert row["work_key"] == _wk(server, "a.archive")
+ assert row["chart_count"] == 2
+
+
+# ── GET charts ───────────────────────────────────────────────────────────────
+
+def test_get_work_charts(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2)
+ _put(server, "b.archive", "Song", "Artist", arrangements=1)
+ body = client.get(f"/api/work/{_wk(server, 'a.archive')}/charts").json()
+ assert body["count"] == 2
+ assert {c["filename"] for c in body["charts"]} == {"a.archive", "b.archive"}
+ assert _rep(body)["filename"] == "a.archive" # auto-pick = most arrangements
+ assert body["preferred_source"] == "auto"
+ assert body["preferred_filename"] is None
+
+
+def test_charts_include_best_accuracy(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "b.archive", "Song", "Artist")
+ server.meta_db.record_session("a.archive", 0, score=900, accuracy=0.9)
+ charts = {c["filename"]: c for c in
+ client.get(f"/api/work/{_wk(server, 'a.archive')}/charts").json()["charts"]}
+ assert charts["a.archive"]["best_accuracy"] == 0.9
+ assert charts["b.archive"]["best_accuracy"] is None
+
+
+# ── PUT / DELETE preferred ───────────────────────────────────────────────────
+
+def test_set_preferred(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2)
+ _put(server, "b.archive", "Song", "Artist", arrangements=1)
+ wk = _wk(server, "a.archive")
+ body = client.put(f"/api/work/{wk}/preferred", json={"filename": "b.archive"}).json()
+ assert body["preferred_filename"] == "b.archive" and body["preferred_source"] == "user"
+ assert _rep(body)["filename"] == "b.archive" and _rep(body)["is_preferred"]
+ # the grouped grid now shows b as the work's card
+ assert client.get("/api/library", params={"group": 1}).json()["songs"][0]["filename"] == "b.archive"
+
+
+def test_set_preferred_nonmember_is_400(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "x.archive", "Other", "Artist")
+ wk = _wk(server, "a.archive")
+ assert client.put(f"/api/work/{wk}/preferred", json={"filename": "x.archive"}).status_code == 400
+ assert client.put(f"/api/work/{wk}/preferred", json={}).status_code == 400
+
+
+def test_reset_preferred_returns_to_auto(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=2)
+ _put(server, "b.archive", "Song", "Artist", arrangements=1)
+ wk = _wk(server, "a.archive")
+ client.put(f"/api/work/{wk}/preferred", json={"filename": "b.archive"})
+ body = client.delete(f"/api/work/{wk}/preferred").json()
+ assert body["preferred_source"] == "auto"
+ assert _rep(body)["filename"] == "a.archive" # auto-pick again
+
+
+# ── split / unsplit ──────────────────────────────────────────────────────────
+
+def test_split_and_unsplit_endpoints(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "b.archive", "Song", "Artist")
+ wk = _wk(server, "a.archive")
+ assert client.get(f"/api/work/{wk}/charts").json()["count"] == 2
+ assert client.post("/api/chart/b.archive/split").json()["ok"] is True
+ assert {c["filename"] for c in client.get(f"/api/work/{wk}/charts").json()["charts"]} == {"a.archive"}
+ assert client.get("/api/library", params={"group": 1}).json()["total"] == 2 # two works now
+ assert client.post("/api/chart/b.archive/unsplit").json()["ok"] is True
+ assert client.get(f"/api/work/{wk}/charts").json()["count"] == 2 # rejoined
+
+
+# ── GET chart work membership (P5d — tree/ungrouped opener resolve) ──────────
+
+def test_chart_work_grouped_pair(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "b.archive", "Song", "Artist")
+ wk = _wk(server, "a.archive")
+ for fn in ("a.archive", "b.archive"):
+ body = client.get(f"/api/chart/{fn}/work").json()
+ assert body == {"filename": fn, "work_key": wk, "chart_count": 2,
+ "is_split": False}
+
+
+def test_chart_work_singleton(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ body = client.get("/api/chart/a.archive/work").json()
+ assert body["work_key"] == _wk(server, "a.archive")
+ assert body["chart_count"] == 1
+
+
+def test_chart_work_split_resolves_to_singleton_key(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "b.archive", "Song", "Artist")
+ wk = _wk(server, "a.archive")
+ client.post("/api/chart/b.archive/split")
+ body = client.get("/api/chart/b.archive/work").json()
+ # the split chart stands alone under its EFFECTIVE (split) key…
+ assert body["work_key"] != wk and body["chart_count"] == 1
+ # …and its key round-trips into the charts endpoint as its own work.
+ # Split keys contain '#' — clients MUST URL-encode the work_key in the
+ # path (the v3 client encodeURIComponent's it) or the '#' truncates the
+ # URL as a fragment.
+ from urllib.parse import quote
+ charts = client.get(f"/api/work/{quote(body['work_key'], safe='')}/charts").json()
+ assert [c["filename"] for c in charts["charts"]] == ["b.archive"]
+ # the chart left behind is a singleton too
+ assert client.get("/api/chart/a.archive/work").json()["chart_count"] == 1
+
+
+def test_chart_work_unknown_file(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ body = client.get("/api/chart/nope.archive/work").json()
+ assert body["work_key"] is None and body["chart_count"] == 0
diff --git a/tests/test_work_grouping.py b/tests/test_work_grouping.py
new file mode 100644
index 0000000..db3ca32
--- /dev/null
+++ b/tests/test_work_grouping.py
@@ -0,0 +1,200 @@
+"""Tests for the multi-chart grouping engine (P5a): several charts (feedpak rows)
+of the same WORK collapse to one representative card via a materialized
+work_display read-model + a `group=1` `WHERE is_group_representative=1` predicate.
+Counting works (not charts), auto-pick, chart_group_pref, split, and keyset
+paging under grouping all stay correct."""
+
+import importlib
+import sys
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture()
+def server(tmp_path, monkeypatch, isolate_logging):
+ monkeypatch.setenv("CONFIG_DIR", str(tmp_path))
+ monkeypatch.setenv("FEEDBACK_SKIP_STARTUP_TASKS", "1")
+ sys.modules.pop("server", None)
+ srv = importlib.import_module("server")
+ try:
+ yield srv
+ finally:
+ conn = getattr(getattr(srv, "meta_db", None), "conn", None)
+ if conn is not None:
+ conn.close()
+ sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+ return TestClient(server.app)
+
+
+def _put(server, fn, title, artist, arrangements=1, mtime=0.0):
+ arr = [{"name": "Lead", "index": i} for i in range(arrangements)]
+ server.meta_db.put(fn, mtime, 0, {"title": title, "artist": artist, "arrangements": arr})
+
+
+def _grouped(client, **params):
+ params["group"] = 1
+ return client.get("/api/library", params=params).json()
+
+
+# ── Baseline: ungrouped shows every chart ────────────────────────────────────
+
+def test_ungrouped_shows_all_charts(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "b.archive", "Song", "Artist")
+ body = client.get("/api/library").json()
+ assert body["total"] == 2
+ assert {s["filename"] for s in body["songs"]} == {"a.archive", "b.archive"}
+ # ungrouped rows carry no chart_count (only the grouped path attaches it)
+ assert "chart_count" not in body["songs"][0]
+
+
+# ── Grouping collapses a work to one representative ───────────────────────────
+
+def test_grouping_collapses_to_one_representative(client, server):
+ _put(server, "a.archive", "Song", "Artist", arrangements=1)
+ _put(server, "b.archive", "Song", "Artist", arrangements=2)
+ body = _grouped(client)
+ assert body["total"] == 1
+ assert len(body["songs"]) == 1
+ rep = body["songs"][0]
+ assert rep["filename"] == "b.archive" # most arrangements wins auto-pick
+ assert rep["chart_count"] == 2
+
+
+def test_autopick_plays_tiebreak(client, server):
+ _put(server, "a.archive", "S", "A", arrangements=1)
+ _put(server, "b.archive", "S", "A", arrangements=1)
+ server.meta_db.record_session("a.archive", 0, score=100, accuracy=0.5) # a has a play
+ assert _grouped(client)["songs"][0]["filename"] == "a.archive"
+
+
+def test_autopick_filename_tiebreak(client, server):
+ _put(server, "b.archive", "S", "A")
+ _put(server, "a.archive", "S", "A")
+ # equal arrangements + plays + mtime → lowest filename
+ assert _grouped(client)["songs"][0]["filename"] == "a.archive"
+
+
+# ── chart_group_pref override ────────────────────────────────────────────────
+
+def test_preferred_overrides_autopick(client, server):
+ _put(server, "a.archive", "S", "A", arrangements=2) # would auto-win
+ _put(server, "b.archive", "S", "A", arrangements=1)
+ wk = server.meta_db.work_key_for("b.archive")
+ server.meta_db.set_chart_preferred(wk, "b.archive")
+ assert _grouped(client)["songs"][0]["filename"] == "b.archive"
+
+
+def test_set_preferred_incremental_reflip(client, server):
+ _put(server, "a.archive", "S", "A", arrangements=2)
+ _put(server, "b.archive", "S", "A", arrangements=1)
+ assert _grouped(client)["songs"][0]["filename"] == "a.archive" # builds read-model
+ wk = server.meta_db.work_key_for("a.archive")
+ server.meta_db.set_chart_preferred(wk, "b.archive") # incremental re-flip
+ body = _grouped(client)
+ assert body["songs"][0]["filename"] == "b.archive"
+ assert body["songs"][0]["chart_count"] == 2 # group_size unchanged
+
+
+def test_clear_preferred_returns_to_autopick(client, server):
+ _put(server, "a.archive", "S", "A", arrangements=2)
+ _put(server, "b.archive", "S", "A", arrangements=1)
+ wk = server.meta_db.work_key_for("a.archive")
+ server.meta_db.set_chart_preferred(wk, "b.archive")
+ assert _grouped(client)["songs"][0]["filename"] == "b.archive"
+ server.meta_db.clear_chart_preferred(wk)
+ assert _grouped(client)["songs"][0]["filename"] == "a.archive" # auto again
+
+
+# ── Split / un-split ─────────────────────────────────────────────────────────
+
+def test_split_makes_singleton(client, server):
+ _put(server, "a.archive", "S", "A")
+ _put(server, "b.archive", "S", "A")
+ assert _grouped(client)["total"] == 1
+ server.meta_db.split_chart("b.archive")
+ body = _grouped(client)
+ assert body["total"] == 2 # two works now
+ assert {s["filename"] for s in body["songs"]} == {"a.archive", "b.archive"}
+ assert all(s["chart_count"] == 1 for s in body["songs"])
+
+
+def test_unsplit_rejoins(client, server):
+ _put(server, "a.archive", "S", "A")
+ _put(server, "b.archive", "S", "A")
+ server.meta_db.split_chart("b.archive")
+ assert _grouped(client)["total"] == 2
+ server.meta_db.unsplit_chart("b.archive")
+ assert _grouped(client)["total"] == 1
+
+
+# ── Stats + A–Z count works, not charts ──────────────────────────────────────
+
+def test_stats_counts_works_not_charts(client, server):
+ _put(server, "a.archive", "Song", "Artist")
+ _put(server, "b.archive", "Song", "Artist") # same work as a
+ _put(server, "c.archive", "Other", "Artist")
+ assert client.get("/api/library/stats").json()["total_songs"] == 3
+ assert client.get("/api/library/stats", params={"group": 1}).json()["total_songs"] == 2
+
+
+def test_sort_letters_counts_works(client, server):
+ _put(server, "a.archive", "Song", "Alpha")
+ _put(server, "b.archive", "Song", "Alpha") # same work
+ _put(server, "c.archive", "Track", "Beta")
+ sl = client.get("/api/library/stats",
+ params={"group": 1, "sort_letters": 1, "sort": "artist"}).json()["sort_letters"]
+ assert sl.get("A") == 1 and sl.get("B") == 1
+
+
+# ── Keyset paging under grouping (the critical integration) ───────────────────
+
+def test_grouped_keyset_pagination(client, server):
+ for i in range(5):
+ _put(server, f"w{i}_a.archive", f"Song {i}", "Artist")
+ _put(server, f"w{i}_b.archive", f"Song {i}", "Artist") # 2 charts per work
+ body = client.get("/api/library", params={"group": 1, "size": 3}).json()
+ assert body["total"] == 5 and len(body["songs"]) == 3
+ cur = body["next_cursor"]
+ assert cur
+ body2 = client.get("/api/library", params={"group": 1, "size": 3, "after": cur}).json()
+ assert len(body2["songs"]) == 2
+ p1 = {s["filename"] for s in body["songs"]}
+ p2 = {s["filename"] for s in body2["songs"]}
+ assert not (p1 & p2) # no skip / dupe across pages
+
+
+# ── Freshness: adding a chart regroups; overrides survive reindex ─────────────
+
+def test_new_chart_updates_group_size(client, server):
+ _put(server, "a.archive", "S", "A")
+ assert _grouped(client)["songs"][0]["chart_count"] == 1
+ _put(server, "b.archive", "S", "A") # dirties read-model
+ body = _grouped(client)
+ assert body["total"] == 1 and body["songs"][0]["chart_count"] == 2
+
+
+def test_preferred_survives_reindex(client, server):
+ _put(server, "a.archive", "S", "A", arrangements=2)
+ _put(server, "b.archive", "S", "A", arrangements=1)
+ wk = server.meta_db.work_key_for("b.archive")
+ server.meta_db.set_chart_preferred(wk, "b.archive")
+ assert _grouped(client)["songs"][0]["filename"] == "b.archive"
+ # A rescan re-indexes both charts (INSERT OR REPLACE INTO songs).
+ _put(server, "a.archive", "S", "A", arrangements=2)
+ _put(server, "b.archive", "S", "A", arrangements=1)
+ assert _grouped(client)["songs"][0]["filename"] == "b.archive" # pref survived
+
+
+# ── work_key normalization folds trivial differences ─────────────────────────
+
+def test_work_key_folds_the_and_punctuation(server):
+ wk = server.meta_db._work_key
+ assert wk("The Beatles", "Hey Jude") == wk("beatles", "hey jude!")
+ assert wk("AC/DC", "T.N.T.") == wk("acdc", "tnt")
+ assert wk("Metallica", "One") != wk("Metallica", "Two")
' +
+ '
' +
+ switchNote +
+ '' +
+ '
' +
+ '' +
+ '' + esc(head.title) + '
' + + '' + esc(head.artist) + ' · ' + data.count + ' chart' + (data.count === 1 ? '' : 's') + '
' +
+ '' +
+ data.charts.map((c) => _chartRowHtml(c, data)).join('') +
+ '
' +
+ (data.preferred_source === 'user'
+ ? ''
+ : 'Auto pick sticks with a chart you\'ve practised; otherwise most complete → newest. Tap a chart to pin your keeper.
') +
+ '