feat(library): Match→Details "use these values" bridge

Connects the popup's two tabs. A match only improves the underlying canon+art;
by design it never silently re-titles the grid. This adds the explicit opt-in
path: each Match candidate (search or Identify-by-audio) gets a "Use these
values →" action that copies its title/artist/album/year into the Details tab
as pending (unsaved) inputs and lands you there for review — pinning the match
too so the art/canon follow. You then Save (overlay) or Write to file. Queue-
review candidates are unchanged (they still accept/pin on click).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -8,12 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`lib/gp_autosync.py`: piecewise time-warp helpers + a working `refine_sync()`.** `auto_sync()` has always computed per-bar sync points (DTW), but consumers could only apply the scalar bar-1 `audio_offset`, so any tempo difference between the recording and the tab's authored tempo accumulated audibly over the song. New librosa-free helpers expose the full mapping: `bar_start_times(gp_path)` (per-bar score times on the same axis as the sync points — GPIF bar-resolution map for `.gp`/`.gpx`, per-tick integration for GP3/4/5), `build_warp_anchors(points, bar_starts)` (strictly-monotonic `(score, audio)` anchor pairs), `warp_time(t, anchors)` (piecewise-linear map with edge-slope extrapolation for count-ins/tails), `warp_song_times(song, warp)` (retimes a `lib.song.Song` in place: notes + sustains, chords, beats, sections, anchors, handshapes, per-phrase difficulty levels, tone changes, tempo overrides), and `gp_has_expandable_repeats(gp_path)` (detects GP3/4/5 repeat/volta/direction markup whose playback expansion the as-written sync points cannot map — callers fall back to offset-only sync). Also implements `refine_sync()`, which the editor plugin's refine-sync endpoint has imported since the snapshot but which never existed in core (the Refine button 500'd): it densifies the coarse DTW points to every Nth bar and re-times each with a local onset phase sweep (sweep radius clamped under half a beat so periodic material can't lock a full beat off; short scoring grid + median residual snap). Synthetic click-track validation: ~13ms mean / ~40ms max error from ±180ms coarse input across 117–123 BPM recordings of a 120 BPM tab. Tests: `tests/test_gp_autosync_warp.py`.
 - **Playlist shuffle.** The v3 playlist detail page gains a crossing-arrows shuffle toggle next to Play all / Play album. When on, `playQueue.start` Fisher-Yates-shuffles the queue once at start (on a copy — the stored playlist order is untouched), swapping any per-slot album arrangements in lockstep so each slot keeps its pinned arrangement. The preference is global and persists in `localStorage` (`v3PlaylistShuffle`). Tests: `tests/js/play_queue_shuffle.test.js`.
 
 ### Changed
 - **Player frame-time hotspots removed (trace-backed) + weak-hardware hardening.** A Chrome performance trace of a 3D-highway session surfaced two core per-frame layout-thrash sources, now fixed: the highway's visibility check read `canvas.offsetParent` every rAF frame (forces style/layout recalc — now sampled every 10th frame with a cached value, force-refreshed on init/canvas-replace/resize/override-clear), and the v3 player chrome loop called `matches(':hover')` per frame and unconditionally rewrote the Up-Next pill's `textContent`/bar width at 6 Hz (now hover-tracked via mouseenter/mouseleave, DOM writes only on value change, progress bar moved from `width` to compositor-only `scaleX`). The 3D highway pre-warms shader programs (`ren.compile`) and deterministic label textures at init — and chart-dependent chord/section label textures on first draw — so first-appearance shader-compile/texture-upload frame spikes move into the load spinner. For weaker hardware: the per-frame renderer bundle is now a single reused object instead of a fresh ~35-field allocation per frame (object identity is stable and meaningless; array fields still swap reference on chart changes), custom viz get `bundle.lowerBoundT`/`bundle.lowerBoundTime` binary-search helpers for visible-window culling, the default 2D highway's beat lines no longer scan every beat in the song per frame, and the 3D highway stops reading `localStorage` per frame (1 Hz poll) and caches its lyrics text-measurement layout per displayed line instead of re-measuring every syllable every frame. A second, throttled-CPU trace pass additionally removed: shader-program re-resolution churn from label texture swaps (`material.needsUpdate` is now only set on a null↔texture transition — swapping between two cached label textures never changes the compiled program), the 3D highway's per-frame `getBoundingClientRect` layout read in its canvas-size self-check (now every 10th frame, still immediate on backing-store change), and the core 60 Hz HUD clock rewriting `textContent` on every tick (now write-on-change, ~1/s). The dominant residual — steady `getParameters` shader-program re-resolution (~4% of throttled main thread) — turned out to be Three r158+'s transparent-DoubleSide two-pass rendering, which sets `material.needsUpdate` twice per object per frame; all 18 of the 3D highway's transparent DoubleSide materials are flat unlit quads (labels, rails, chord frames, lanes), so they now declare `forceSinglePass: true`, eliminating the recompile churn and halving those objects' draw calls.
 
 ### Fixed
+- **Guitar Pro 6 (`.gpx`) import no longer fails on every real file.** The GPX BCFS container reader (`lib/gp2rs_gpx.py`) rejected any file whose final sector wasn't a full `0x1000` block — but a real `.gpx`'s BCFZ-declared decompressed size isn't sector-aligned, so the last (small) container file always lands in a partial trailing sector. The bounds check *raised* `GPX BCFS sector pointer out of range (malformed file)` instead of clamping the tail read, so `_load_gpif` threw before `score.gpif` could be extracted and **no GP6 file could be imported into the song editor** (both real test files failed identically — this wasn't file-specific). GP7/GP8 `.gp` files were unaffected — they take the ZIP path, not BCFS, which is why prior GP-import work didn't surface it. The reader now **clamps the final sector read to the buffer end** (the per-file size field trims the padding anyway), matching canonical GPX readers (alphaTab / PyGuitarPro); a sector whose *start* is past the end still raises, preserving the malformed-file guard. Verified against two real GP6 files — both now unpack to valid GPIF with all tracks. Tests: `tests/test_gp2rs_gpx.py` (partial-final-sector round-trip, multi-file container, sector-aligned baseline, and the preserved out-of-range guard).
+- **v3 Songs grid: fixed the scroll stutter that "skips every so many scrolls," up or down.** The virtualized grid rebuilt its **entire** visible window (`grid.innerHTML = …` + a full `wireCards` pass) every time it slid by one row, so each row-boundary crossing was a heavy synchronous frame that stalled the main thread and buffered held-arrow key-repeats into a visible lurch (a tester's "super fast for a second then slowed down") at fixed scroll offsets — in **both directions and regardless of whether the page was already loaded** (the cost was DOM teardown, not fetching, which is why scrolling back up over cached songs hitched too). `renderWindow()` now **reconciles the window in place**: it reuses the card nodes that stay on-screen and builds only the row that enters/leaves (~6 nodes per slide instead of ~60), keyed by absolute index with a real-vs-skeleton + select-mode signature so hole-fills (after a page fetch) and select-mode toggles still rebuild exactly the nodes that changed. `wireCards`'s `data-wired` guard then wires only the freshly-built nodes, so per-slide listener churn drops with it. Follow-up to the stage-2 virtualized grid (got-feedback/feedBack#636 item 3). Frontend-only: `static/v3/songs.js`. Tests: `tests/js/v3_songs_window_recycle.test.js` (window stays `[start,end)` contiguous + in-window node identity reused across a down-then-up scroll; select-mode toggle and rail-seek jump rebuild correctly).
+- **Starter content seeds again (and now ships The Adicts' "Ode to Joy").** `_BUILTIN_STARTER_SOURCES` still listed `beethoven-ode_to_joy.feedpak` after that pack was deleted, and never wired up its replacement `the_adicts-ode-to-joy_vst_cover.feedpak` that landed on disk. The listed-but-missing file made the all-present gate never fire, so **no** starter songs seeded on first run. Synced the manifest to what's on disk (Für Elise, Star Spangled Banner, The Adicts' Ode to Joy). Tests: `tests/test_builtin_starter_seed.py` (the present/unlisted guards were red on `main`).
 - **Edit Metadata now writes into `.feedpak` files, not just legacy `.sloppak` ones.** `lib/songmeta.py`'s suffix gate predated the format rename — core reads both suffixes everywhere else (`sloppak.SONG_EXTS`), but the metadata writer only dispatched on `.sloppak`, so editing a zip-form `.feedpak`'s title/artist/album/year silently fell back to a DB-only update. That looked fine until the next **full library rescan** re-derived metadata from the file and reverted the edit (directory-form packages were unaffected — they dispatch on manifest presence, not suffix). The gate now accepts both package suffixes. Tests: `tests/test_songmeta.py` `TestWriteSongMetadata` (both zip suffixes, mixed-case suffix, directory form, unknown-suffix fallback).
 - **3D Drum & Keys highways now re-frame on fullscreen/layout drift under splitscreen.** The guitar/bass `highway_3d` self-detects when its panel canvas changes size and re-runs `applySize()` every frame, because the splitscreen host overrides `hw.resize` and never calls `renderer.resize()`. The drum and keys highways lacked that fallback — they only re-framed when the host explicitly called `resize(w, h)` — so their panels stayed framed for the pre-fullscreen size while the guitar/bass panels adapted (visible as a too-small, off-center highway after maximizing a split-screen session). Both draw loops now port `highway_3d`'s per-frame drift check: they re-apply on backing-store change (`canvas.width/height`) AND on CSS-box drift (`clientWidth/clientHeight` vs the last applied logical size, throttled to every 10th frame), and reset the tracking in `destroy()` so a reused instance re-frames on the next song. `plugins/drum_highway_3d` → 0.3.1, `plugins/keys_highway_3d` → 0.1.1. Tests: `tests/js/drum_keys_highway_3d_resize_reframe.test.js`.
 - **Tuner: finished the "remove unused settings" cleanup and fixed the sidebar panel position.** The Floating Button and Tuning Visibility settings sections were removed, but their config was still live: `disabledTunings` still filtered the tuner menu (with no UI left to re-enable a hidden tuning — a one-way trap) and `showFloatingButton` still gated the floating launcher. Both are now fully retired — the enforcement paths in `plugins/tuner/screen.js`/`utils/ui.js` and the persistence in `plugins/tuner/routes.py` are gone (and `routes.py` strips the retired keys on write, so stale values are purged). The tuner panel opened from the v3 sidebar Plugins rail popover now anchors beside it via the host's stable plugin-control slot API (falling back to the popover id), is **clamped to the viewport** so it can't open off the right/bottom edge on narrow/short windows, and re-anchors on window resize. `plugins/tuner` → 1.3.3.

lib/gp2rs_gpx.py

@@ -121,10 +121,18 @@ def _parse_bcfs(bcfs: bytes) -> dict:
             while sc <= max_sectors:
                 s = _gi(po + 4 * sc); sc += 1
                 if s == 0: break
-                so = s * SECTOR
-                if HDR + so + SECTOR > len(data):
+                start = HDR + s * SECTOR
+                # Real .gpx files' final sector is a few bytes short of a full
+                # 0x1000 block: the BCFZ-declared decompressed size isn't
+                # sector-aligned, so the last (small) container file lands in a
+                # partial trailing sector. Clamp the read to the buffer end —
+                # the per-file size field (`fs`, applied below) trims any
+                # padding — matching canonical GPX readers (alphaTab /
+                # PyGuitarPro slice-and-clamp). Only a sector whose *start* is
+                # past the end is genuinely malformed.
+                if start < 0 or start >= len(data):
                     raise ValueError("GPX BCFS sector pointer out of range (malformed file)")
-                fb.extend(data[HDR + so: HDR + so + SECTOR])
+                fb.extend(data[start: min(start + SECTOR, len(data))])
             else:
                 raise ValueError("GPX BCFS sector chain too long (malformed file)")
             files[fn] = bytes(fb[:fs])
@@ -1498,6 +1506,10 @@ def convert_file(
     # Surface that to the caller rather than only the docstring: if the score
     # actually uses repeats, the produced bar count/timing will differ from the
     # equivalent .gp5. Warn once so plugin code/logs don't silently drift.
+    # NB: lib/gp_autosync.gp_has_expandable_repeats() encodes this single-pass
+    # behaviour (.gp/.gpx never expand). Implementing GPIF expansion here MUST
+    # update that helper in the same change, or the editor's per-bar sync warp
+    # would silently retime repeated sections onto the wrong bars.
     if expand_repeats and any(
         mb.find('Repeat') is not None or mb.find('AlternateEndings') is not None
         for mb in masterbars

lib/gp_autosync.py

@@ -18,8 +18,22 @@ plugin is installed; graceful ImportError otherwise with clear message).
 Public API:
     is_available()                          -> bool
     auto_sync(gp_path, audio_path, ...)    -> GpSyncData
+    refine_sync(sync, audio_path, ...)     -> GpSyncData
     estimate_audio_offset(gp_path,
                           audio_path)      -> float
+    bar_start_times(gp_path)               -> list[float]
+    gp_has_expandable_repeats(gp_path)     -> bool
+    build_warp_anchors(sync_points,
+                       bar_starts)         -> list[tuple[float, float]]
+    warp_time(t, anchors)                  -> float
+    warp_song_times(song, warp)            -> None
+
+The warp helpers (bar_start_times / build_warp_anchors / warp_time /
+warp_song_times) are librosa-free: they turn a GpSyncData produced by
+auto_sync (or extracted from a GP8 file) into a piecewise-linear
+score-time -> audio-time mapping and apply it to a lib.song.Song, so
+converted charts follow the recording's actual tempo drift instead of a
+single scalar offset.
 """
 
 from __future__ import annotations
@@ -353,15 +367,22 @@ def _synthesise_score_chroma(
     return chroma
 
 _GP345_TICKS_PER_QUARTER = 960
+# PyGuitarPro absolute ticks start at quarterTime (measure 1 begins at tick
+# 960, not 0). All tick math in this module runs on a 0-based axis (cumulative
+# measure starts), so raw beat.start values must be shifted by this origin —
+# mixing the two axes applied every mid-song tempo change a quarter note late
+# and skewed the synthesised chroma against the bar timeline.
+_GP345_TICK_ORIGIN = 960
 
 
 def _gp345_tempo_events(song) -> list[tuple[int, float]]:
     """Sorted, tick-deduplicated ``[(tick, bpm)]`` tempo events for a GP3/4/5 song.
 
     Seeds with the song's initial tempo at tick 0, then appends every
-    ``mixTableChange`` tempo. Shared by chroma synthesis and bar-time
-    computation so both use one identical tempo model (mirrors
-    ``gp2rs._build_tempo_map``).
+    ``mixTableChange`` tempo. Ticks are normalised to the 0-based axis
+    (raw ``beat.start`` minus ``_GP345_TICK_ORIGIN``). Shared by chroma
+    synthesis and bar-time computation so both use one identical tempo
+    model (mirrors ``gp2rs._build_tempo_map``).
     """
     events: list[tuple[int, float]] = [(0, float(song.tempo))]
     for track in song.tracks:
@@ -371,7 +392,10 @@ def _gp345_tempo_events(song) -> list[tuple[int, float]]:
                     if beat.effect and beat.effect.mixTableChange:
                         mtc = beat.effect.mixTableChange
                         if mtc.tempo and mtc.tempo.value > 0:
-                            events.append((beat.start, float(mtc.tempo.value)))
+                            events.append((
+                                max(0, beat.start - _GP345_TICK_ORIGIN),
+                                float(mtc.tempo.value),
+                            ))
     events.sort(key=lambda e: e[0])
     seen_ticks: set[int] = set()
     unique: list[tuple[int, float]] = []
@@ -459,8 +483,9 @@ def _synthesise_score_chroma_gp345(
                 for beat in voice.beats:
                     if not beat.notes:
                         continue
-                    beat_secs = tick_to_secs(beat.start)
-                    cur_tempo = tempo_at_tick(beat.start)
+                    beat_tick = max(0, beat.start - _GP345_TICK_ORIGIN)
+                    beat_secs = tick_to_secs(beat_tick)
+                    cur_tempo = tempo_at_tick(beat_tick)
                     dur_secs = duration_to_secs(beat.duration, cur_tempo)
 
                     for note in beat.notes:
@@ -520,6 +545,45 @@ def _dtw_align(
 
 # ── Sync point extraction from DTW path ──────────────────────────────────────
 
+def _gpif_bar_starts(root: ET.Element) -> list[float]:
+    """Score-time (seconds) at the start of each masterbar in a GPIF score.
+
+    Integrates bar durations from the bar-resolution tempo map and each
+    masterbar's time signature — the same time model _synthesise_score_chroma
+    uses, so bar times land where the bars sit in the synthesised chroma.
+    """
+    tempo_map = _get_tempo_map(root)
+    masterbars = _children(root, 'MasterBars')
+    tempo_iter = iter(tempo_map)
+    next_tb, next_bpm = next(tempo_iter, (999999, tempo_map[0][1]))
+    ct = tempo_map[0][1]
+    t_cur = 0.0
+    bar_starts: list[float] = []
+    for mb_idx, mb in enumerate(masterbars):
+        while mb_idx >= next_tb:
+            ct = next_bpm
+            next_tb, next_bpm = next(tempo_iter, (999999, ct))
+        bar_starts.append(t_cur)
+        ts = mb.findtext('Time', '4/4')
+        try:
+            n_b, d_b = [int(x) for x in ts.split('/')]
+        except ValueError:
+            n_b, d_b = 4, 4
+        t_cur += n_b * (4.0 / d_b) * (60.0 / ct)
+    return bar_starts
+
+
+def _gp345_measure_start_ticks(song) -> list[int]:
+    """Cumulative start tick of each measure in a PyGuitarPro song."""
+    starts: list[int] = []
+    cum = 0
+    for mh in song.measureHeaders:
+        starts.append(cum)
+        ts = mh.timeSignature
+        cum += int(ts.numerator * (4.0 / ts.denominator.value) * _GP345_TICKS_PER_QUARTER)
+    return starts
+
+
 def _extract_sync_points(
     wp: 'np.ndarray',
     root: ET.Element,
@@ -565,22 +629,7 @@ def _extract_sync_points(
     if bar_starts_override is not None:
         bar_starts_score = list(bar_starts_override)
     else:
-        tempo_iter = iter(tempo_map)
-        next_tb, next_bpm = next(tempo_iter, (999999, tempo_map[0][1]))
-        ct = tempo_map[0][1]
-        t_cur = 0.0
-        bar_starts_score = []
-        for mb_idx, mb in enumerate(masterbars):
-            while mb_idx >= next_tb:
-                ct = next_bpm
-                next_tb, next_bpm = next(tempo_iter, (999999, ct))
-            bar_starts_score.append(t_cur)
-            ts = mb.findtext('Time', '4/4')
-            try:
-                n_b, d_b = [int(x) for x in ts.split('/')]
-            except ValueError:
-                n_b, d_b = 4, 4
-            t_cur += n_b * (4.0 / d_b) * (60.0 / ct)
+        bar_starts_score = _gpif_bar_starts(root)
 
     # Map each sampled bar to its audio time via the DTW path
     sync_points: list[SyncPoint] = []
@@ -663,6 +712,224 @@ def _tempo_at_bar(tempo_map: list[tuple[int, float]], bar: int) -> float:
 
 # ── Audio offset estimation ───────────────────────────────────────────────────
 
+# ── Piecewise time warp (librosa-free) ───────────────────────────────────────
+#
+# auto_sync's per-bar sync points describe where each sampled bar of the tab
+# falls in the real recording. Applying only the scalar audio_offset (bar 1)
+# assumes the recording holds the authored tempo for the whole song — any
+# drift accumulates. These helpers build the full piecewise-linear
+# score-time -> audio-time mapping and apply it to a converted Song, so the
+# chart follows the recording bar by bar (Songsterr-style sync).
+
+def bar_start_times(gp_path: str) -> list[float]:
+    """Score-time (seconds) at the start of every bar of a GP file.
+
+    Uses the same tempo models as auto_sync's chroma synthesis (GPIF
+    bar-resolution map for .gp/.gpx, per-tick integration for .gp3/4/5), so
+    the returned times share an axis with auto_sync's sync points.
+
+    Raises ValueError if the file cannot be parsed, ImportError if the file
+    is GP3/4/5 and PyGuitarPro is not installed.
+    """
+    try:
+        root = _load_gpif(gp_path)
+    except _Gp345FileError:
+        import guitarpro
+        try:
+            song = guitarpro.parse(gp_path)
+        except Exception as exc:
+            raise ValueError(f"Cannot parse GP3/4/5 file {gp_path!r}: {exc}") from exc
+        tempo_events = _gp345_tempo_events(song)
+        return [
+            _gp345_tick_to_secs(tempo_events, tick)
+            for tick in _gp345_measure_start_ticks(song)
+        ]
+    return _gpif_bar_starts(root)
+
+
+def gp_has_expandable_repeats(gp_path: str) -> bool:
+    """True when converting `gp_path` expands repeats into a longer timeline
+    than the as-written score auto_sync aligned against.
+
+    gp2rs.convert_file walks the GP3/4/5 playback graph (repeat brackets,
+    voltas, D.S./D.C. directions), so a file using any of those produces an
+    as-performed timeline that auto_sync's as-written sync points cannot be
+    mapped onto. GPIF (.gp/.gpx) conversion is single-pass as-written today,
+    so those files always return False — both sides share one bar order.
+
+    Returns False when the file cannot be parsed (callers fall back to
+    offset-only sync on parse failure anyway).
+    """
+    if Path(gp_path).suffix.lower() in ('.gp', '.gpx'):
+        return False
+    try:
+        import guitarpro
+        song = guitarpro.parse(gp_path)
+    except Exception:
+        return False
+    for mh in song.measureHeaders:
+        if mh.isRepeatOpen or mh.repeatClose >= 0 or mh.repeatAlternative:
+            return True
+        # Both jump SOURCES (fromDirection: D.C., D.S., Da Coda) and jump
+        # TARGETS (direction: Segno, Coda, Fine) count — a plain Da Capo
+        # needs no target marker, so checking `direction` alone would miss
+        # it while gp2rs's playback walker still expands the jump.
+        if (getattr(mh, 'direction', None) is not None
+                or getattr(mh, 'fromDirection', None) is not None):
+            return True
+    return False
+
+
+def build_warp_anchors(
+    sync_points: list[SyncPoint],
+    bar_starts: list[float],
+) -> list[tuple[float, float]]:
+    """Turn sync points into (score_secs, audio_secs) anchor pairs.
+
+    Drops points whose bar index is out of range, points that would break
+    strict monotonicity on either axis (DTW can locally fold on noisy audio;
+    a non-monotonic anchor would make the warp non-invertible and reorder
+    notes), and points whose segment slope implies a physically implausible
+    tempo ratio (outside 0.2x-5x authored). Returns [] when fewer than 2
+    usable anchors remain — callers should fall back to scalar-offset sync
+    in that case.
+    """
+    anchors: list[tuple[float, float]] = []
+    for sp in sorted(sync_points, key=lambda p: p.bar):
+        if not 0 <= sp.bar < len(bar_starts):
+            continue
+        score_t = bar_starts[sp.bar]
+        audio_t = float(sp.time_secs)
+        if anchors and (score_t <= anchors[-1][0] + 1e-6
+                        or audio_t <= anchors[-1][1] + 1e-3):
+            continue
+        if anchors:
+            # Slope sanity gate: a segment whose audio/score tempo ratio is
+            # outside [0.2, 5] is not a performance — it's a DTW fold onto a
+            # repeated section, an abridged recording, or a run of
+            # monotonicity-clamped refine points. Keeping it would crush (or
+            # absurdly stretch) every bar in the span, which is far worse
+            # than interpolating through from the neighbouring anchors.
+            slope = (audio_t - anchors[-1][1]) / (score_t - anchors[-1][0])
+            if not 0.2 <= slope <= 5.0:
+                continue
+        anchors.append((score_t, audio_t))
+    return anchors if len(anchors) >= 2 else []
+
+
+def warp_time(t: float, anchors: list[tuple[float, float]]) -> float:
+    """Map a score-time (seconds) to audio-time via piecewise-linear anchors.
+
+    Between anchors: linear interpolation. Outside the anchor range: the
+    nearest segment's slope is extended, so a count-in before bar 1 and the
+    tail after the last sampled bar keep the local tempo ratio.
+
+    `anchors` must be the >=2-point strictly-monotonic list produced by
+    build_warp_anchors.
+    """
+    lo = 0
+    hi = len(anchors) - 1
+    if t <= anchors[0][0]:
+        seg = (anchors[0], anchors[1])
+    elif t >= anchors[hi][0]:
+        seg = (anchors[hi - 1], anchors[hi])
+    else:
+        # Binary search for the segment containing t
+        while hi - lo > 1:
+            mid = (lo + hi) // 2
+            if anchors[mid][0] <= t:
+                lo = mid
+            else:
+                hi = mid
+        seg = (anchors[lo], anchors[hi])
+    (s0, a0), (s1, a1) = seg
+    slope = (a1 - a0) / (s1 - s0)
+    return a0 + (t - s0) * slope
+
+
+def warp_song_times(song, warp) -> None:
+    """Apply a monotonic time-mapping callable to every absolute time in a
+    lib.song.Song, in place.
+
+    Covers beats, sections, song_length, and per-arrangement notes (onset +
+    sustain), chords (incl. chord notes), anchors, hand shapes, per-phrase
+    difficulty levels, tone changes, and tempo overrides. Durations (note
+    sustain, handshape span) are warped as end-start so they stretch with the
+    local tempo ratio; sub-second intra-note envelopes (bend curves, which are
+    relative to the note onset) are left untouched.
+
+    Duck-typed: accepts any object with the lib.song.Song surface.
+
+    Identity-safe: parse_arrangement shares the SAME Note/Chord/Anchor/
+    HandShape objects between the flat arrangement lists and the
+    max-difficulty phrase level, so each object is warped at most once no
+    matter how many containers reference it.
+    """
+    seen: set[int] = set()
+
+    def _once(obj) -> bool:
+        key = id(obj)
+        if key in seen:
+            return False
+        seen.add(key)
+        return True
+
+    def _warp_notes(notes):
+        for n in notes or []:
+            if not _once(n):
+                continue
+            end = warp(n.time + n.sustain)
+            n.time = warp(n.time)
+            n.sustain = max(0.0, end - n.time)
+
+    def _warp_chords(chords):
+        for c in chords or []:
+            if not _once(c):
+                continue
+            c.time = warp(c.time)
+            _warp_notes(c.notes)
+
+    def _warp_anchors(anchors):
+        for a in anchors or []:
+            if _once(a):
+                a.time = warp(a.time)
+
+    def _warp_handshapes(shapes):
+        for h in shapes or []:
+            if not _once(h):
+                continue
+            start = warp(h.start_time)
+            end = warp(h.end_time)
+            h.start_time = start
+            h.end_time = max(start, end)
+
+    song.song_length = max(0.0, warp(song.song_length))
+    for b in song.beats:
+        b.time = warp(b.time)
+    for s in song.sections:
+        s.start_time = warp(s.start_time)
+    for arr in song.arrangements:
+        _warp_notes(arr.notes)
+        _warp_chords(arr.chords)
+        _warp_anchors(arr.anchors)
+        _warp_handshapes(arr.hand_shapes)
+        for ph in arr.phrases or []:
+            ph.start_time = warp(ph.start_time)
+            ph.end_time = warp(ph.end_time)
+            for lvl in ph.levels or []:
+                _warp_notes(lvl.notes)
+                _warp_chords(lvl.chords)
+                _warp_anchors(lvl.anchors)
+                _warp_handshapes(lvl.hand_shapes)
+        if arr.tones and isinstance(arr.tones, dict):
+            for change in arr.tones.get('changes') or []:
+                if isinstance(change, dict) and isinstance(change.get('t'), (int, float)):
+                    change['t'] = warp(float(change['t']))
+        for tempo_ev in arr.tempos or []:
+            if isinstance(tempo_ev, dict) and isinstance(tempo_ev.get('time'), (int, float)):
+                tempo_ev['time'] = warp(float(tempo_ev['time']))
+
+
 def _estimate_audio_offset(
     root: ET.Element,
     audio_path: str,
@@ -932,12 +1199,7 @@ def auto_sync(
         # below line up with the chroma timeline.
         _tempo_events_gp345 = _gp345_tempo_events(_gp345x_song)
         # Convert tick events to bar events using actual measure start ticks
-        _measure_starts = []  # cumulative tick at start of each bar
-        _cum = 0
-        for _mh2 in _gp345x_song.measureHeaders:
-            _measure_starts.append(_cum)
-            _ts = _mh2.timeSignature
-            _cum += int(_ts.numerator * (4.0 / _ts.denominator.value) * _GP345_TICKS_PER_QUARTER)
+        _measure_starts = _gp345_measure_start_ticks(_gp345x_song)
 
         def _tick_to_bar(tick):
             """Return 0-based bar index for a given tick position."""
@@ -1024,6 +1286,216 @@ def auto_sync(
         sync_points=sync_points,
     )
 
+def refine_sync(
+    sync: GpSyncData,
+    audio_path: str,
+    bars_per_point: int = 8,
+    gp_path: str | None = None,
+    sr: int = _SR,
+    search_radius: float = 0.35,
+    phase_step: float = 0.005,
+    onset_tolerance: float = 0.05,
+) -> GpSyncData:
+    """Refine coarse DTW sync points with a per-bar onset phase sweep.
+
+    auto_sync's mid-song points inherit the DTW frame granularity (~186ms at
+    the default hop). This pass re-times a denser grid of bars — every
+    `bars_per_point`-th bar plus the first and last — by sweeping a local
+    beat grid (±`search_radius`s in `phase_step` steps) against detected
+    onsets and keeping the phase that aligns best, narrowing each kept point
+    to roughly the phase-step resolution on percussive material.
+
+    Args:
+        sync:            Coarse sync data from auto_sync (or a prior refine).
+        audio_path:      The same audio file auto_sync aligned against.
+        bars_per_point:  Refined-point density; every Nth bar gets a point.
+        gp_path:         Optional path to the GP file. When given, exact
+                         per-bar score times (bar_start_times) drive the
+                         densified grid; without it the grid is limited to
+                         a 4/4 approximation built from the points' authored
+                         tempos, and accuracy degrades on odd meters.
+        sr:              Analysis sample rate.
+        search_radius:   ±seconds around each coarse estimate to sweep.
+        phase_step:      Sweep resolution in seconds.
+        onset_tolerance: Max onset-to-click distance that counts as aligned.
+
+    Returns:
+        A new GpSyncData with the refined (and usually denser) points and a
+        recomputed audio_offset. Returns `sync` unchanged when it has no
+        usable points. Quiet bars (fewer than 4 onsets nearby) keep their
+        coarse interpolated time rather than locking onto noise.
+    """
+    if not sync.sync_points:
+        return sync
+
+    pts = sorted(sync.sync_points, key=lambda p: p.bar)
+
+    bar_starts: list[float] | None = None
+    if gp_path:
+        try:
+            bar_starts = bar_start_times(gp_path)
+        except Exception as exc:
+            _log.warning("refine_sync: bar_start_times(%s) failed (%s) — "
+                         "falling back to 4/4 tempo model", gp_path, exc)
+    if bar_starts is None:
+        # Approximate score bar starts from the points' authored tempos,
+        # assuming 4 beats per bar (all GpSyncData carries without the file).
+        max_bar = pts[-1].bar
+        bar_starts = [0.0]
+        ti = 0
+        cur_bpm = pts[0].original_tempo or 120.0
+        for b in range(1, max_bar + 1):
+            while ti + 1 < len(pts) and pts[ti + 1].bar <= b - 1:
+                ti += 1
+                cur_bpm = pts[ti].original_tempo or cur_bpm
+            bar_starts.append(bar_starts[-1] + 4 * 60.0 / max(cur_bpm, 1e-3))
+
+    anchors = build_warp_anchors(pts, bar_starts)
+    if len(anchors) < 2:
+        _log.warning("refine_sync: fewer than 2 usable anchors — returning "
+                     "input unchanged")
+        return sync
+
+    # Authored-tempo lookup via the shared bar-map scan (_tempo_at_bar) so
+    # boundary semantics can't drift from the rest of the module.
+    _orig_map = [(p.bar, p.original_tempo or 120.0) for p in pts]
+
+    def _orig_bpm_at(bar: int) -> float:
+        return max(_tempo_at_bar(_orig_map, bar), 1e-3)
+
+    n_bars = len(bar_starts)
+    step = max(1, int(bars_per_point))
+    targets = sorted(set(range(0, n_bars, step)) | {n_bars - 1})
+
+    # Deferred past the pure early-return paths above so degenerate inputs
+    # (no points, <2 anchors) resolve without librosa installed.
+    import librosa
+    import numpy as np
+
+    y, _ = librosa.load(audio_path, sr=sr, mono=True)
+    audio_dur = len(y) / sr
+    hop = 512  # ~23ms at 22050Hz — fine enough for onset timing
+    onset_frames = librosa.onset.onset_detect(
+        y=y, sr=sr, hop_length=hop, backtrack=True
+    )
+    onset_times = np.asarray(
+        librosa.frames_to_time(onset_frames, sr=sr, hop_length=hop)
+    )
+
+    refined: list[tuple[int, float]] = []
+    for b in targets:
+        score_t = bar_starts[b]
+        coarse = warp_time(score_t, anchors)
+        if coarse > audio_dur + 1.0:
+            break  # bar falls past the end of the recording
+        # Local beat period in AUDIO time: authored beat period scaled by the
+        # local warp slope (recording tempo / authored tempo around this bar).
+        slope = warp_time(score_t + 1.0, anchors) - coarse
+        slope = min(max(slope, 0.25), 4.0)
+        beat_period = (60.0 / _orig_bpm_at(b)) * slope
+
+        # Keep the scoring grid short: beat_period is estimated from the
+        # coarse anchors (a few % off), and grid drift grows linearly with
+        # distance — 16 beats at 2% error is already ~150ms of skew at the
+        # far end, which drags the sweep. 8 beats bounds that to ~beat noise.
+        grid_span = 8 * beat_period
+        # Clamp the sweep window below half a beat so the neighbouring beat
+        # is never a candidate — on periodic material (steady drums) a grid
+        # shifted by one whole beat scores identically and the sweep could
+        # lock a full beat off. DTW coarse error is ~1 analysis frame, which
+        # this window still covers at all but extreme tempos.
+        radius = min(search_radius, 0.45 * beat_period)
+        w_lo = coarse - radius - onset_tolerance
+        w_hi = coarse + radius + grid_span + onset_tolerance
+        local = onset_times[(onset_times >= w_lo) & (onset_times <= w_hi)]
+        if len(local) < 4:
+            refined.append((b, coarse))
+            continue
+
+        best_t, best_score, best_dist = coarse, -1, 0.0
+        for phase in np.arange(coarse - radius, coarse + radius + 1e-9,
+                               phase_step):
+            clicks = np.arange(phase, phase + grid_span, beat_period)
+            score = int(sum(
+                1 for t in local
+                if float(np.min(np.abs(clicks - t))) < onset_tolerance
+            ))
+            dist = abs(float(phase) - coarse)
+            # Ties break toward the coarse estimate so a flat score surface
+            # (sustained pads, sparse onsets) can't drag the point sideways.
+            if score > best_score or (score == best_score and dist < best_dist):
+                best_score, best_t, best_dist = score, float(phase), dist
+
+        # A sweep that matched almost nothing found a spurious edge
+        # alignment, not the beat grid — this happens when the true phase
+        # lies outside the (ambiguity-clamped) window, e.g. fast tempos
+        # where the DTW coarse error exceeds half a beat. Keeping the
+        # coarse estimate degrades gracefully instead of locking a
+        # fraction of a beat off.
+        if best_score < 3:
+            refined.append((b, coarse))
+            continue
+
+        # The onset-count score is flat within ±onset_tolerance of the true
+        # phase, so the sweep alone can be off by up to the tolerance. Snap
+        # inside that plateau: shift by the median residual between matched
+        # onsets and their nearest grid click. Only the first few beats
+        # count here — they are nearly insensitive to beat_period error,
+        # while far clicks would leak that error into the residuals.
+        if best_score > 0:
+            clicks = np.arange(best_t, best_t + 4 * beat_period + 1e-9,
+                               beat_period)
+            residuals = []
+            for t in local:
+                d = clicks - float(t)
+                j = int(np.argmin(np.abs(d)))
+                if abs(d[j]) < onset_tolerance:
+                    residuals.append(-float(d[j]))  # onset minus click
+            if residuals:
+                best_t += float(np.median(residuals))
+        refined.append((b, best_t))
+
+    if not refined:
+        return sync
+
+    # Enforce monotonicity: a point refined earlier than its predecessor
+    # would fold the warp. Clamp to a small positive gap.
+    mono: list[tuple[int, float]] = []
+    prev_t: float | None = None
+    for b, t in refined:
+        t = max(t, 0.0)
+        if prev_t is not None and t <= prev_t + 0.02:
+            t = prev_t + 0.02
+        mono.append((b, t))
+        prev_t = t
+
+    # Recompute per-segment modified tempos from the refined times (same
+    # formula _extract_sync_points uses; the last point carries the previous
+    # segment's tempo forward).
+    new_points: list[SyncPoint] = []
+    for i, (b, t) in enumerate(mono):
+        obpm = _orig_bpm_at(b)
+        if i + 1 < len(mono):
+            b2, t2 = mono[i + 1]
+            score_seg = bar_starts[b2] - bar_starts[b]
+            audio_seg = t2 - t
+            mod = obpm * (score_seg / audio_seg) if audio_seg > 1e-3 else obpm
+            mod = max(20.0, min(300.0, mod))
+        else:
+            mod = new_points[-1].modified_tempo if new_points else obpm
+        new_points.append(SyncPoint(
+            bar=b, time_secs=t, modified_tempo=mod, original_tempo=obpm,
+        ))
+
+    _log.info("refine_sync: %d points (was %d), audio_offset=%.3fs",
+              len(new_points), len(pts), -new_points[0].time_secs)
+    return GpSyncData(
+        audio_offset=-new_points[0].time_secs,
+        audio_asset_id=sync.audio_asset_id,
+        sync_points=new_points,
+    )
+
+
 def estimate_audio_offset(gp_path: str, audio_path: str) -> float:
     """
     Estimate the audio_offset for a GP file aligned to an audio file.

lib/mb_match.py

@@ -39,6 +39,14 @@ DURATION_BONUS_LOOSE = 0.025   # …within 15s
 _DURATION_TIGHT = 5
 _DURATION_LOOSE = 15
 
+# Release-group secondary types that mark a NON-canonical release (a live album,
+# a greatest-hits comp, a remix/DJ set, …). Used both to pick the canonical
+# studio album for display and to reward studio recordings in ranking.
+_SECONDARY_SKIP = {
+    "live", "compilation", "remix", "dj-mix", "mixtape/street",
+    "demo", "interview", "audiobook", "spokenword",
+}
+
 # ── Denoise ───────────────────────────────────────────────────────────────────
 # A parenthetical/bracketed group is dropped when it contains any of these
 # noise terms as a whole word (chart-variant markers, tuning/pitch notes,
@@ -136,12 +144,31 @@ def _duration_int(v):
         return None
 
 
+def cand_artist_sim(song: dict, cand: dict) -> float:
+    """Best artist similarity between the song's reference artist and the
+    candidate's PRIMARY name OR any of its `artist_aliases` (romanized/alternate
+    names). MusicBrainz stores many artists under a non-Latin primary name
+    (大橋純子) with the romanized form ("Junko Ohashi") only as an alias, so a
+    reference typed/derived in romaji scores 0 against the primary but 1.0
+    against the alias. The caller (server) attaches `artist_aliases` only for
+    promising near-misses, so this is a plain max when they're present and the
+    original single comparison when they're not."""
+    best = similarity(song.get("artist"), cand.get("artist"), artist=True)
+    for alias in cand.get("artist_aliases") or []:
+        if best >= 1.0:
+            break
+        s = similarity(song.get("artist"), alias, artist=True)
+        if s > best:
+            best = s
+    return best
+
+
 def score_candidate(song: dict, cand: dict) -> float:
     """Combined confidence that MusicBrainz candidate `cand` is the song the
     chart transcribes. 0.5*artist + 0.5*title, plus small year/duration
     corroboration bonuses, capped at 1.0. Missing fields score 0 on their
     half — classify() separately refuses to auto-match without both."""
-    artist_sim = similarity(song.get("artist"), cand.get("artist"), artist=True)
+    artist_sim = cand_artist_sim(song, cand)
     title_sim = similarity(song.get("title"), cand.get("title"))
     score = 0.5 * artist_sim + 0.5 * title_sim
     sy, cy = _year_int(song.get("year")), _year_int(cand.get("year"))
@@ -154,6 +181,10 @@ def score_candidate(song: dict, cand: dict) -> float:
             score += DURATION_BONUS
         elif diff <= _DURATION_LOOSE:
             score += DURATION_BONUS_LOOSE
+    # NB: the studio-vs-live distinction is deliberately NOT scored here — a live
+    # take is still the RIGHT SONG (same title/artist), so it must not change the
+    # auto/review confidence. Canonical-version preference lives in the RANK sort
+    # (rank_candidates) instead, where it only reorders same-song candidates.
     return min(score, 1.0)
 
 
@@ -168,7 +199,7 @@ def classify(song: dict, cand: dict, score: float, auto_min: float | None = None
     """
     if auto_min is None:
         auto_min = AUTO_MIN
-    artist_sim = similarity(song.get("artist"), cand.get("artist"), artist=True)
+    artist_sim = cand_artist_sim(song, cand)
     title_sim = similarity(song.get("title"), cand.get("title"))
     if (score >= auto_min and artist_sim >= AUTO_ARTIST_MIN
             and title_sim >= AUTO_TITLE_MIN):
@@ -179,15 +210,34 @@ def classify(song: dict, cand: dict, score: float, auto_min: float | None = None
 
 
 def rank_candidates(song: dict, candidates: list[dict]) -> list[dict]:
-    """Score every candidate against the song and return them sorted by our
-    score (MusicBrainz's own search score is only a tiebreak). Each returned
-    dict is a copy carrying `score` (rounded — it's displayed and stored)."""
+    """Score every candidate against the song and return them sorted best-first.
+    The combined `score` caps at 1.0, so a perfect-text-match query (every "AC/DC
+    Highway to Hell" recording) ties at the top — there the studio flag and, when
+    the caller knows the audio length, the duration match break the tie so the
+    canonical studio take wins over live/promo/extended cuts. Each returned dict
+    is a copy carrying `score` (rounded — it's displayed and stored)."""
+    sd = _duration_int(song.get("duration"))
+    # For a chart that IS a live take (build_recording_query keeps live
+    # recordings for these) the studio take is the WRONG recording, so drop the
+    # studio tiebreak — duration proximity + text/mb score then pick the right
+    # live version instead of auto-matching the studio one.
+    prefer_studio = not _LIVE_GROUP_RE.search(str(song.get("title") or ""))
+
+    def _dur_diff(c):
+        cd = _duration_int(c.get("duration"))
+        return abs(sd - cd) if (sd and cd) else 10 ** 6
+
     ranked = []
     for cand in candidates or []:
         c = dict(cand)
         c["score"] = round(score_candidate(song, cand), 4)
         ranked.append(c)
-    ranked.sort(key=lambda c: (c["score"], c.get("mb_score") or 0), reverse=True)
+    ranked.sort(
+        key=lambda c: (c["score"],
+                       (1 if c.get("studio") else 0) if prefer_studio else 0,
+                       -_dur_diff(c),                 # closest to the audio length
+                       c.get("mb_score") or 0),
+        reverse=True)
     return ranked
 
 
@@ -198,18 +248,63 @@ def _lucene_escape_phrase(s: str) -> str:
     return s.replace("\\", "\\\\").replace('"', '\\"')
 
 
-def build_recording_query(artist, title) -> str:
+# A parenthetical/bracketed "(Live …)" marker — the live signal denoise() strips
+# from the title. Mirrors _NOISE_GROUP_RE but for the `live` term only.
+_LIVE_GROUP_RE = re.compile(r"[(\[][^)\]]*\blive\b[^)\]]*[)\]]", re.IGNORECASE)
+
+
+def build_recording_query(artist, title, *, loose: bool = False) -> str:
     """Lucene query for /ws/2/recording. Built from the DENOISED fields —
     the noise we strip (author credits, "(Live)", "(v2)") would otherwise
-    poison the search server's own scoring."""
+    poison the search server's own scoring.
+
+    ``loose=True`` drops the field-scoped quoted PHRASES for plain AND-ed
+    term groups (``(telephone number) AND (junko ohashi)``). The point:
+    a field phrase like ``artist:"Junko Ohashi"`` only matches MusicBrainz's
+    *primary* artist name — it never searches ALIASES — so a recording stored
+    under a non-Latin primary (大橋純子) whose romanized name is only an alias
+    is invisible to the strict query. A loose term query searches the whole
+    document, aliases included, and surfaces it. Lower precision by design: it
+    is a FALLBACK for when the strict query returns nothing, and its results
+    are re-scored by ``rank_candidates`` (and, for auto-match, gated by the
+    per-field floors), so noise never auto-applies."""
     t = denoise(title)
     a = denoise(artist)
+    if loose:
+        # denoise() already reduced each field to lowercase [a-z0-9 and] tokens
+        # (punctuation → spaces, diacritics stripped, & → "and"), so no
+        # Lucene-special character survives to need escaping. Group each field's
+        # terms and require both groups.
+        q = " AND ".join("(%s)" % g for g in (t, a) if g)
+        # Keep the SAME live exclusion as the strict path: the loose query is
+        # lower-precision, and score_candidate doesn't penalize a live take, so
+        # without this a studio chart whose strict query missed could fall back
+        # to — and auto-confirm — a live-only recording. Skipped only when the
+        # source title is itself a live take (mirrors the strict path).
+        if q and not _LIVE_GROUP_RE.search(str(title or "")):
+            q += " AND -secondarytype:Live"
+        return q
     parts = []
     if t:
         parts.append('recording:"%s"' % _lucene_escape_phrase(t))
     if a:
         parts.append('artist:"%s"' % _lucene_escape_phrase(a))
-    return " AND ".join(parts)
+    q = " AND ".join(parts)
+    # Drop live-ONLY recordings (bootlegs, live albums) — the canonical studio
+    # take is never tagged Live, and this is the single biggest source of junk in
+    # a flat recording search. Compilations are deliberately NOT excluded: they
+    # REUSE the studio recording, so filtering them would drop the very recording
+    # we want (verified against MusicBrainz — `-secondarytype:Compilation` cut the
+    # AC/DC studio "Highway to Hell" recording entirely).
+    #
+    # EXCEPT when the source chart is itself a live take: denoise() strips the
+    # "(Live at …)" qualifier from the query, so filtering Live would leave the
+    # genuinely-live chart with NO correct recording. Only a parenthetical marker
+    # counts — a bare title word ("Live and Let Die") is a real word, not a live
+    # tag — mirroring what denoise removes.
+    if q and not _LIVE_GROUP_RE.search(str(title or "")):
+        q += " AND -secondarytype:Live"
+    return q
 
 
 def _artist_credit(doc: dict) -> tuple[str, str, str]:
@@ -226,19 +321,33 @@ def _artist_credit(doc: dict) -> tuple[str, str, str]:
     return name, str(artist.get("id", "") or ""), str(artist.get("sort-name", "") or "")
 
 
+def _is_clean_studio_album(rg: dict) -> bool:
+    """A release-group that is a primary-type Album with NO non-canonical
+    secondary type (Live / Compilation / Remix / …) — i.e. a studio album."""
+    if str(rg.get("primary-type", "")).lower() != "album":
+        return False
+    secs = {str(s).lower() for s in (rg.get("secondary-types") or [])}
+    return not (secs & _SECONDARY_SKIP)
+
+
 def _best_release(doc: dict) -> dict:
-    """Pick the release used for canon album/year: prefer Official status and
-    an Album release-group, then the earliest date. Returns {} if none."""
+    """Pick the release used for canon album/year: prefer an OFFICIAL studio
+    Album (primary Album with no Live/Compilation/… secondary type), then the
+    earliest date. Falls back to any release when none is clean. {} if none."""
     releases = [r for r in (doc.get("releases") or []) if isinstance(r, dict)]
     if not releases:
         return {}
 
     def sort_key(r):
-        status_ok = 0 if str(r.get("status", "")).lower() == "official" else 1
         rg = r.get("release-group") or {}
-        album_ok = 0 if str(rg.get("primary-type", "")).lower() == "album" else 1
+        clean = 0 if _is_clean_studio_album(rg) else 1
+        status_ok = 0 if str(r.get("status", "")).lower() == "official" else 1
         date = str(r.get("date", "") or "9999")
-        return (status_ok, album_ok, date)
+        # Official FIRST, then prefer a clean studio album: this still surfaces
+        # the studio album over an (official) live/comp album for the display
+        # album/year, but never lets an UNofficial bootleg album outrank an
+        # official single/EP/comp — which `(clean, status_ok, …)` would.
+        return (status_ok, clean, date)
 
     return sorted(releases, key=sort_key)[0]
 
@@ -261,6 +370,7 @@ def parse_recording_doc(doc: dict) -> dict | None:
         return None
     artist_name, artist_id, artist_sort = _artist_credit(doc)
     release = _best_release(doc)
+    studio = _is_clean_studio_album(release.get("release-group") or {})
     length = doc.get("length")
     try:
         duration = int(round(float(length) / 1000.0)) if length else None
@@ -281,6 +391,7 @@ def parse_recording_doc(doc: dict) -> dict | None:
         "isrc": isrcs[0] if isrcs else "",
         "genres": _genres(doc),
         "mb_score": int(doc.get("score") or 0),
+        "studio": studio,
     }
 
 

lib/safepath.py

@@ -26,6 +26,13 @@ def safe_join(root: Path, name: str) -> Path | None:
     """
     if not name:
         return None
+    # Reject embedded NULs explicitly. This used to ride on `.resolve()`
+    # raising ValueError, but on Python 3.13 (Windows) resolve() no longer
+    # raises for an embedded NUL, so the byte would otherwise leak through
+    # containment. An explicit guard is strictly-more-rejection (no effect on
+    # the zip-slip / traversal contract).
+    if "\x00" in name:
+        return None
     safe = name.replace("\\", "/")
     try:
         root_resolved = root.resolve()

lib/tunings.py

@@ -4,51 +4,132 @@ Kept separate from server.py so tests can import it without triggering
 FastAPI / SQLite module-level side effects.
 """
 
+from __future__ import annotations
+
+import math
+
 DEFAULT_REFERENCE_PITCH = 440.0
 
-# Canonical tuning frequencies at 440 Hz reference, keyed by instrument then
-# tuning name. This is the authoritative source; tuner/routes.py previously
-# held a copy — it was removed in favour of this one.
-DEFAULT_TUNINGS: dict[str, dict[str, list[float]]] = {
+# Canonical open strings, low to high, as MIDI notes. This is the host-level
+# source of truth for guitar/bass tuning profiles; UI surfaces derive names,
+# frequencies, and semitone offsets from these absolute pitches.
+STANDARD_OPEN_MIDIS: dict[str, list[int]] = {
+    "guitar-6": [40, 45, 50, 55, 59, 64],
+    "guitar-7": [35, 40, 45, 50, 55, 59, 64],
+    "guitar-8": [30, 35, 40, 45, 50, 55, 59, 64],
+    "bass-4": [28, 33, 38, 43],
+    "bass-5": [23, 28, 33, 38, 43],
+    "bass-6": [23, 28, 33, 38, 43, 48],
+}
+
+# Curated built-in profiles. This intentionally starts by absorbing the useful
+# Virtuoso guitar/bass coverage into host-owned data so the host selector,
+# tuner, practice tools, and plugins can converge on one profile model.
+TUNING_PRESET_MIDIS: dict[str, dict[str, list[int]]] = {
     "guitar-6": {
-        "Standard":    [82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "Eb Standard": [77.78, 103.83, 138.59, 185.00, 233.08, 311.13],
-        "Drop D":      [73.42, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "D Standard":  [73.42,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Drop C":      [65.41,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Open G":      [73.42,  98.00, 146.83, 196.00, 246.94, 293.66],
-        "Open D":      [73.42, 110.00, 146.83, 185.00, 220.00, 293.66],
-        "DADGAD":      [73.42, 110.00, 146.83, 196.00, 220.00, 293.66],
-        "Open E":      [82.41, 123.47, 164.81, 207.65, 246.94, 329.63],
+        "Standard": [40, 45, 50, 55, 59, 64],
+        "Eb Standard": [39, 44, 49, 54, 58, 63],
+        "D Standard": [38, 43, 48, 53, 57, 62],
+        "C# Standard": [37, 42, 47, 52, 56, 61],
+        "C Standard": [36, 41, 46, 51, 55, 60],
+        "Drop D": [38, 45, 50, 55, 59, 64],
+        "Drop C": [36, 43, 48, 53, 57, 62],
+        "Drop B": [35, 42, 47, 52, 56, 61],
+        "Drop A": [33, 40, 45, 50, 54, 59],
+        "Drop Ab": [32, 39, 44, 49, 53, 58],
+        "Open G": [38, 43, 50, 55, 59, 62],
+        "Open D": [38, 45, 50, 54, 57, 62],
+        "DADGAD": [38, 45, 50, 55, 57, 62],
+        "Open E": [40, 47, 52, 56, 59, 64],
     },
     "guitar-7": {
-        "Standard":    [61.74, 82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "Drop A":      [55.00, 82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "A Standard":  [55.00, 73.42,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Drop G":      [49.00, 73.42, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "Bb Standard": [58.27, 77.78, 103.83, 138.59, 185.00, 233.08, 311.13],
+        "Standard": [35, 40, 45, 50, 55, 59, 64],
+        "Bb Standard": [34, 39, 44, 49, 54, 58, 63],
+        "A Standard": [33, 38, 43, 48, 53, 57, 62],
+        "G Standard": [31, 36, 41, 46, 51, 55, 60],
+        "Drop A": [33, 40, 45, 50, 55, 59, 64],
+        "Drop G": [31, 38, 43, 48, 53, 57, 62],
+        "Drop F#": [30, 37, 42, 47, 52, 56, 61],
     },
     "guitar-8": {
-        "Standard":    [46.25, 61.74, 82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "Drop E":      [41.20, 61.74, 82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
-        "E Standard":  [41.20, 55.00, 73.42,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Drop D":      [36.71, 55.00, 73.42,  98.00, 130.81, 174.61, 220.00, 293.66],
-        "Eb Standard": [38.89, 51.91, 69.30,  92.50, 123.47, 164.81, 207.65, 277.18],
+        "Standard": [30, 35, 40, 45, 50, 55, 59, 64],
+        "Drop E": [28, 35, 40, 45, 50, 55, 59, 64],
+        "Drop A + Drop E": [28, 33, 40, 45, 50, 55, 59, 64],
+        "E Standard": [28, 33, 38, 43, 48, 53, 57, 62],
+        "Eb Standard": [27, 32, 37, 42, 47, 52, 56, 61],
+        "Drop D": [26, 33, 38, 43, 48, 53, 57, 62],
     },
     "bass-4": {
-        "Standard":    [41.20, 55.00, 73.42,  98.00],
-        "Eb Standard": [38.89, 51.91, 69.30,  92.50],
-        "Drop D":      [36.71, 55.00, 73.42,  98.00],
-        "D Standard":  [36.71, 48.99, 65.41,  87.31],
-        "Drop C":      [32.70, 48.99, 65.41,  87.31],
+        "Standard": [28, 33, 38, 43],
+        "Eb Standard": [27, 32, 37, 42],
+        "D Standard": [26, 31, 36, 41],
+        "C# Standard": [25, 30, 35, 40],
+        "C Standard": [24, 29, 34, 39],
+        "Drop D": [26, 33, 38, 43],
+        "Drop C": [24, 31, 36, 41],
+        "BEAD": [23, 28, 33, 38],
     },
     "bass-5": {
-        "Standard":    [30.87, 41.20, 55.00, 73.42,  98.00],
-        "Eb Standard": [29.14, 38.89, 51.91, 69.30,  92.50],
-        "Drop D":      [30.87, 36.71, 55.00, 73.42,  98.00],
-        "D Standard":  [27.50, 36.71, 48.99, 65.41,  87.31],
-        "Drop C":      [27.50, 32.70, 48.99, 65.41,  87.31],
+        "Standard": [23, 28, 33, 38, 43],
+        "High C": [28, 33, 38, 43, 48],
+        "Eb Standard": [22, 27, 32, 37, 42],
+        "D Standard": [21, 26, 31, 36, 41],
+        "C# Standard": [20, 25, 30, 35, 40],
+        "C Standard": [19, 24, 29, 34, 39],
+        "Drop A": [21, 28, 33, 38, 43],
     },
+    "bass-6": {
+        "Standard": [23, 28, 33, 38, 43, 48],
+        "Eb Standard": [22, 27, 32, 37, 42, 47],
+        "D Standard": [21, 26, 31, 36, 41, 46],
+        "C# Standard": [20, 25, 30, 35, 40, 45],
+        "C Standard": [19, 24, 29, 34, 39, 44],
+    },
+}
+
+
+def midi_to_freq(midi: int, reference_pitch: float = DEFAULT_REFERENCE_PITCH) -> float:
+    """Return the frequency for a MIDI note at the supplied A4 reference."""
+    return reference_pitch * math.pow(2, (midi - 69) / 12)
+
+
+def open_midis_to_freqs(midis: list[int], reference_pitch: float = DEFAULT_REFERENCE_PITCH) -> list[float]:
+    """Return rounded frequencies for low-to-high MIDI open strings."""
+    return [round(midi_to_freq(m, reference_pitch), 2) for m in midis]
+
+
+def tuning_offsets_from_midis(instrument_key: str, midis: list[int]) -> list[int] | None:
+    """Return semitone offsets from the instrument's standard open strings."""
+    standard = STANDARD_OPEN_MIDIS.get(instrument_key)
+    if not standard or len(standard) != len(midis):
+        return None
+    return [int(m - s) for m, s in zip(midis, standard)]
+
+
+def tuning_midis_from_offsets(instrument_key: str, offsets: list[int]) -> list[int] | None:
+    """Return absolute open-string MIDI notes for host semitone offsets."""
+    standard = STANDARD_OPEN_MIDIS.get(instrument_key)
+    if not standard or len(standard) != len(offsets):
+        return None
+    return [int(s + o) for s, o in zip(standard, offsets)]
+
+
+def tuning_preset_offsets(instrument_key: str, name: str) -> list[int] | None:
+    """Return host semitone offsets for a named preset."""
+    midis = TUNING_PRESET_MIDIS.get(instrument_key, {}).get(name)
+    if not midis:
+        return None
+    return tuning_offsets_from_midis(instrument_key, midis)
+
+
+# Canonical tuning frequencies at 440 Hz reference, keyed by instrument then
+# tuning name. Kept for the existing /api/tunings contract.
+DEFAULT_TUNINGS: dict[str, dict[str, list[float]]] = {
+    instrument: {
+        name: open_midis_to_freqs(midis)
+        for name, midis in presets.items()
+    }
+    for instrument, presets in TUNING_PRESET_MIDIS.items()
 }
 
 
@@ -67,6 +148,256 @@ def apply_reference_pitch(
     }
 
 
+PROFILE_IDS = ("guitar-lead", "guitar-rhythm", "bass")
+PROFILE_PATHWAYS = ("songs", "practice", "learn", "studio")
+DEFAULT_ACTIVE_INSTRUMENT_PROFILE = "guitar-lead"
+PROFILE_DEFAULTS: dict[str, dict] = {
+    "guitar-lead": {
+        "id": "guitar-lead",
+        "label": "Lead Guitar",
+        "instrument": "guitar",
+        "role": "lead",
+        "string_count": 6,
+        "tuning": "Standard",
+        "reference_pitch": DEFAULT_REFERENCE_PITCH,
+        "pathway": "songs",
+    },
+    "guitar-rhythm": {
+        "id": "guitar-rhythm",
+        "label": "Rhythm Guitar",
+        "instrument": "guitar",
+        "role": "rhythm",
+        "string_count": 6,
+        "tuning": "Standard",
+        "reference_pitch": DEFAULT_REFERENCE_PITCH,
+        "pathway": "songs",
+    },
+    "bass": {
+        "id": "bass",
+        "label": "Bass",
+        "instrument": "bass",
+        "role": "bass",
+        "string_count": 4,
+        "tuning": "Standard",
+        "reference_pitch": DEFAULT_REFERENCE_PITCH,
+        "pathway": "songs",
+    },
+}
+
+
+def instrument_key(instrument: str, string_count: int) -> str:
+    return f"{instrument}-{string_count}"
+
+
+def default_instrument_profiles() -> dict[str, dict]:
+    return {profile_id: dict(profile) for profile_id, profile in PROFILE_DEFAULTS.items()}
+
+
+def _valid_reference_pitch(value) -> float | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        ref = float(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if not math.isfinite(ref) or ref < 430.0 or ref > 450.0:
+        return None
+    return ref
+
+
+def _valid_tuning_for_key(key: str, tuning):
+    if isinstance(tuning, str):
+        if len(tuning) > 64:
+            return None
+        if tuning in TUNING_PRESET_MIDIS.get(key, {}):
+            return tuning
+        # A name that IS a built-in preset for a different key is a misapplied
+        # built-in (e.g. "Drop D" on a 5-string bass, whose low string is B) —
+        # reject it. A name unknown to every built-in table is a provider/custom
+        # tuning (the tuner plugin's, exposed via /api/tunings) that this pure
+        # layer can't resolve — accept it so settings round-trip; the provider
+        # owns its validity.
+        if any(tuning in names for names in TUNING_PRESET_MIDIS.values()):
+            return None
+        return tuning
+    if isinstance(tuning, list):
+        expected = len(STANDARD_OPEN_MIDIS.get(key, []))
+        if len(tuning) != expected:
+            return None
+        if any(isinstance(o, bool) or not isinstance(o, int) or o < -12 or o > 12 for o in tuning):
+            return None
+        return list(tuning)
+    return None
+
+
+def normalize_instrument_profile(profile_id: str, raw) -> tuple[dict | None, str | None]:
+    """Validate one persisted host instrument profile."""
+    base = dict(PROFILE_DEFAULTS.get(profile_id, {}))
+    if not base:
+        return None, f"unknown instrument profile: {profile_id}"
+    if raw is None:
+        return base, None
+    if not isinstance(raw, dict):
+        return None, f"instrument_profiles.{profile_id} must be an object"
+
+    instrument = raw.get("instrument", base["instrument"])
+    if instrument not in ("guitar", "bass"):
+        return None, f"instrument_profiles.{profile_id}.instrument must be 'guitar' or 'bass'"
+
+    try:
+        string_count = int(raw.get("string_count", base["string_count"]))
+    except (TypeError, ValueError, OverflowError):
+        return None, f"instrument_profiles.{profile_id}.string_count must be valid for the instrument"
+    key = instrument_key(instrument, string_count)
+    if key not in STANDARD_OPEN_MIDIS:
+        return None, f"instrument_profiles.{profile_id}.string_count must be valid for the instrument"
+
+    tuning = _valid_tuning_for_key(key, raw.get("tuning", base["tuning"]))
+    if tuning is None:
+        return None, f"instrument_profiles.{profile_id}.tuning must match {key}"
+
+    ref = _valid_reference_pitch(raw.get("reference_pitch", base["reference_pitch"]))
+    if ref is None:
+        return None, f"instrument_profiles.{profile_id}.reference_pitch must be a number between 430 and 450"
+
+    label = raw.get("label", base["label"])
+    if not isinstance(label, str) or len(label) > 64:
+        return None, f"instrument_profiles.{profile_id}.label must be a short string"
+    role = raw.get("role", base["role"])
+    if not isinstance(role, str) or len(role) > 32:
+        return None, f"instrument_profiles.{profile_id}.role must be a short string"
+    pathway = raw.get("pathway", base["pathway"])
+    if not isinstance(pathway, str) or pathway not in PROFILE_PATHWAYS:
+        return None, f"instrument_profiles.{profile_id}.pathway must be one of songs, practice, learn, studio"
+
+    out = dict(base)
+    out.update({
+        "id": profile_id,
+        "label": label,
+        "instrument": instrument,
+        "role": role,
+        "string_count": string_count,
+        "tuning": tuning,
+        "reference_pitch": ref,
+        "pathway": pathway,
+    })
+    return out, None
+
+
+def normalize_instrument_profiles(raw_profiles=None) -> tuple[dict[str, dict] | None, str | None]:
+    """Validate persisted host profiles, filling omitted built-ins with defaults."""
+    if raw_profiles is None:
+        return default_instrument_profiles(), None
+    if not isinstance(raw_profiles, dict):
+        return None, "instrument_profiles must be an object"
+    profiles = {}
+    for profile_id in PROFILE_IDS:
+        profile, error = normalize_instrument_profile(profile_id, raw_profiles.get(profile_id))
+        if error:
+            return None, error
+        profiles[profile_id] = profile
+    return profiles, None
+
+
+def active_profile_id(raw) -> str:
+    return raw if raw in PROFILE_DEFAULTS else DEFAULT_ACTIVE_INSTRUMENT_PROFILE
+
+
+def profile_from_legacy_settings(cfg: dict) -> dict:
+    """Build an active profile from the old flat settings keys."""
+    instrument = cfg.get("instrument") if cfg.get("instrument") in ("guitar", "bass") else "guitar"
+    fallback_sc = 4 if instrument == "bass" else 6
+    try:
+        sc = int(cfg.get("string_count", fallback_sc))
+    except (TypeError, ValueError, OverflowError):
+        sc = fallback_sc
+    key = instrument_key(instrument, sc)
+    if key not in STANDARD_OPEN_MIDIS:
+        sc = fallback_sc
+        key = instrument_key(instrument, sc)
+    tuning = _valid_tuning_for_key(key, cfg.get("tuning", "Standard")) or "Standard"
+    ref = _valid_reference_pitch(cfg.get("reference_pitch", DEFAULT_REFERENCE_PITCH)) or DEFAULT_REFERENCE_PITCH
+    pathway = cfg.get("pathway") if cfg.get("pathway") in PROFILE_PATHWAYS else "songs"
+    profile_id = "bass" if instrument == "bass" else DEFAULT_ACTIVE_INSTRUMENT_PROFILE
+    profile = dict(PROFILE_DEFAULTS[profile_id])
+    profile.update({
+        "instrument": instrument,
+        "string_count": sc,
+        "tuning": tuning,
+        "reference_pitch": ref,
+        "pathway": pathway,
+    })
+    return profile
+
+
+def settings_with_instrument_profiles(cfg: dict) -> dict:
+    """Return settings with canonical host profiles and mirrored flat keys."""
+    out = dict(cfg)
+    profiles, _error = normalize_instrument_profiles(out.get("instrument_profiles"))
+    if profiles is None:
+        profiles = default_instrument_profiles()
+    if "instrument_profiles" not in out:
+        legacy = profile_from_legacy_settings(out)
+        profiles[legacy["id"]] = legacy
+        # Default the active profile to the one migrated from the legacy flat
+        # fields, but DON'T clobber an explicit request — a fresh-config
+        # `POST {"active_instrument_profile": "bass"}` must switch, not be
+        # overwritten by the guitar-lead inferred from defaults. active_profile_id
+        # below normalizes an invalid value.
+        out.setdefault("active_instrument_profile", legacy["id"])
+    active = active_profile_id(out.get("active_instrument_profile"))
+    selected = profiles[active]
+    out["instrument_profiles"] = profiles
+    out["active_instrument_profile"] = active
+    out["instrument"] = selected["instrument"]
+    out["string_count"] = selected["string_count"]
+    out["tuning"] = selected["tuning"]
+    out["reference_pitch"] = selected["reference_pitch"]
+    out["pathway"] = selected["pathway"]
+    return out
+
+
+def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict) -> dict:
+    """Mirror legacy flat instrument updates into the active host profile."""
+    out = settings_with_instrument_profiles(cfg)
+    if not any(k in updates for k in ("instrument", "string_count", "tuning", "reference_pitch", "pathway")):
+        return out
+    active = active_profile_id(out.get("active_instrument_profile"))
+    if "instrument" in updates:
+        active = "bass" if updates["instrument"] == "bass" else "guitar-lead"
+        out["active_instrument_profile"] = active
+    current = dict(out["instrument_profiles"][active])
+
+    if "instrument" in updates:
+        current["instrument"] = updates["instrument"]
+        if "string_count" not in updates:
+            current["string_count"] = 4 if updates["instrument"] == "bass" else 6
+    if "string_count" in updates:
+        current["string_count"] = updates["string_count"]
+    if "reference_pitch" in updates:
+        current["reference_pitch"] = updates["reference_pitch"]
+    if "pathway" in updates:
+        current["pathway"] = updates["pathway"]
+    if "tuning" in updates:
+        current["tuning"] = updates["tuning"]
+    else:
+        key = instrument_key(current["instrument"], current["string_count"])
+        if _valid_tuning_for_key(key, current.get("tuning")) is None:
+            current["tuning"] = "Standard"
+
+    profile, error = normalize_instrument_profile(active, current)
+    if error:
+        raise ValueError(error)
+    out["instrument_profiles"][active] = profile
+    out.update({
+        "instrument": profile["instrument"],
+        "string_count": profile["string_count"],
+        "tuning": profile["tuning"],
+        "reference_pitch": profile["reference_pitch"],
+        "pathway": profile["pathway"],
+    })
+    return out
+
 def tuning_name(offsets: list[int]) -> str:
     # All three pattern checks below are gated on `len(offsets) == 6`. The
     # naming conventions here are 6-string-specific — e.g. a 7-string all-zeros

server.py

@@ -43,7 +43,12 @@ from song import (
     scale_degree_for_pitch,
 )
 from audio import find_wem_files, convert_wem
-from tunings import tuning_name, DEFAULT_TUNINGS, DEFAULT_REFERENCE_PITCH, apply_reference_pitch
+from tunings import (
+    DEFAULT_REFERENCE_PITCH, DEFAULT_TUNINGS, PROFILE_IDS, PROFILE_PATHWAYS,
+    apply_flat_instrument_patch_to_profiles, apply_reference_pitch,
+    normalize_instrument_profile, normalize_instrument_profiles,
+    settings_with_instrument_profiles, tuning_name,
+)
 import sloppak as sloppak_mod
 import drums as drums_mod
 import notation as notation_mod
@@ -194,6 +199,7 @@ _DEMO_BLOCKED: list[tuple[str, re.Pattern]] = [
     ("DELETE", re.compile(r"^/api/audio-effects/active-mapping$")),
     ("POST",   re.compile(r"^/api/song/.*/meta$")),
     ("POST",   re.compile(r"^/api/song/.*/art/upload$")),
+    ("PUT",    re.compile(r"^/api/song/.+/overrides$")),
     ("GET",    re.compile(r"^/api/plugins/updates$")),
     ("POST",   re.compile(r"^/api/plugins/[^/]+/update$")),
     ("POST",   re.compile(r"^/api/plugins/editor/save$")),
@@ -241,6 +247,8 @@ _DEMO_BLOCKED: list[tuple[str, re.Pattern]] = [
     # anonymous demo visitors (they'd spend the shared rate limit).
     ("POST",   re.compile(r"^/api/enrichment/review/.+$")),
     ("POST",   re.compile(r"^/api/enrichment/kick$")),
+    ("POST",   re.compile(r"^/api/enrichment/cancel$")),
+    ("POST",   re.compile(r"^/api/enrichment/rematch$")),
     ("GET",    re.compile(r"^/api/enrichment/search$")),
     # AcoustID audio fingerprinting: both identify endpoints run fpcalc (CPU)
     # and spend the shared AcoustID rate budget on the caller's behalf — same
@@ -548,7 +556,13 @@ def next_library_cursor(sort: str, last_song: dict | None) -> str | None:
     key = "mtime" if col == "mtime" else col
     if key not in last_song or "filename" not in last_song:
         return None
-    return _encode_cursor([last_song[key], last_song["filename"]])
+    # A title display-override (Fix-metadata popup) replaces last_song["title"]
+    # for the card, but the keyset seek runs on the RAW title column — resume
+    # from the raw value query_page stashed (present only when the last row's
+    # title was overridden), so paging never skips/dupes.
+    val = (last_song["_sort_title"] if (key == "title" and "_sort_title" in last_song)
+           else last_song[key])
+    return _encode_cursor([val, last_song["filename"]])
 
 
 # Song-level "mastered" threshold — best accuracy across a song's arrangements
@@ -660,6 +674,26 @@ class MetadataDB:
             )
         """)
         self.conn.execute("CREATE INDEX IF NOT EXISTS idx_song_tags_tag ON song_tags(tag COLLATE NOCASE)")
+        # Per-field metadata OVERRIDES + LOCKS (the Fix-metadata popup). A
+        # reversible DISPLAY overlay, never written to the pack: `value` is the
+        # user's corrected value for a catalog field (title/artist/album/year/
+        # genre), `locked=1` pins the field so a metadata refresh / auto-match
+        # never changes what's shown for it (Plex-style field lock). Effective
+        # display value = override → matched-MusicBrainz → pack → derived.
+        # Filename-keyed → purged with the song on delete_song, NEVER on a
+        # rescan (delete_missing), so an edit survives re-import like every other
+        # local layer.
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS song_field_override (
+                filename TEXT NOT NULL,
+                field TEXT NOT NULL,        -- title|artist|album|year|genre
+                value TEXT,                 -- corrected value (NULL = lock only, no override)
+                locked INTEGER NOT NULL DEFAULT 0,
+                updated_at TEXT,
+                PRIMARY KEY (filename, field)
+            )
+        """)
+        self.conn.execute("CREATE INDEX IF NOT EXISTS idx_field_override_fn ON song_field_override(filename)")
         # Artist-name aliases (P4): "ACDC" → "AC/DC", "the beatles" → "The Beatles".
         # A CANONICALIZATION OVERRIDE applied AT DISPLAY only — the scanner-derived
         # `songs.artist` and the feedpak files are never rewritten (a rescan can't
@@ -1161,6 +1195,88 @@ class MetadataDB:
             self.conn.commit()
         return self.get_song_user_meta(filename)
 
+    # ── Per-field metadata overrides + locks (Fix-metadata popup) ─────────────
+    def get_song_overrides(self, filename: str) -> dict:
+        """{field: {"value": str|None, "locked": bool}} for one song."""
+        rows = self.conn.execute(
+            "SELECT field, value, locked FROM song_field_override WHERE filename = ?",
+            (filename,)).fetchall()
+        return {r[0]: {"value": r[1], "locked": bool(r[2])} for r in rows}
+
+    def set_song_override(self, filename: str, field: str, *,
+                          value="__keep__", locked="__keep__") -> dict:
+        """Partial upsert of one field's override value and/or lock. Pass a
+        value/locked to set it or leave the sentinel to keep the current one. A
+        row with neither a value nor a lock is dropped (no empty shell). Returns
+        the song's full override map."""
+        with self._lock:
+            cur = self.conn.execute(
+                "SELECT value, locked FROM song_field_override WHERE filename = ? AND field = ?",
+                (filename, field)).fetchone()
+            new_val = (cur[0] if cur else None) if value == "__keep__" else value
+            new_lock = (bool(cur[1]) if cur else False) if locked == "__keep__" else bool(locked)
+            new_val = (new_val or "").strip() or None
+            if new_val is None and not new_lock:
+                self.conn.execute(
+                    "DELETE FROM song_field_override WHERE filename = ? AND field = ?",
+                    (filename, field))
+            else:
+                self.conn.execute(
+                    "INSERT INTO song_field_override (filename, field, value, locked, updated_at) "
+                    "VALUES (?, ?, ?, ?, datetime('now')) "
+                    "ON CONFLICT(filename, field) DO UPDATE SET "
+                    "value = excluded.value, locked = excluded.locked, updated_at = excluded.updated_at",
+                    (filename, field, new_val, 1 if new_lock else 0))
+            self.conn.commit()
+        return self.get_song_overrides(filename)
+
+    def locked_fields(self, filename: str) -> set:
+        """The catalog fields the user LOCKED for a song (Fix-metadata popup).
+        An automatic match must never (re)canonicalize these, and gap-fill must
+        never write them to the file. Locked read (the enrichment worker calls
+        it), minimal projection."""
+        with self._lock:
+            return {r[0] for r in self.conn.execute(
+                "SELECT field FROM song_field_override WHERE filename = ? AND locked = 1",
+                (filename,)).fetchall()}
+
+    def clear_song_override(self, filename: str, field: str) -> dict:
+        """Remove a field's override + lock entirely (revert to the resolved
+        pack/matched value)."""
+        with self._lock:
+            self.conn.execute(
+                "DELETE FROM song_field_override WHERE filename = ? AND field = ?",
+                (filename, field))
+            self.conn.commit()
+        return self.get_song_overrides(filename)
+
+    def overrides_map(self, filenames) -> dict:
+        """{filename: {field: {value, locked}}} for a batch — feeds the grid's
+        effective-value resolution (display slice). Chunked under SQLite's
+        variable limit."""
+        fns = list(filenames)
+        out: dict = {}
+        for i in range(0, len(fns), 400):
+            chunk = fns[i:i + 400]
+            if not chunk:
+                break
+            q = ("SELECT filename, field, value, locked FROM song_field_override "
+                 "WHERE filename IN (%s)" % ",".join("?" * len(chunk)))
+            for fn, field, value, locked in self.conn.execute(q, chunk).fetchall():
+                out.setdefault(fn, {})[field] = {"value": value, "locked": bool(locked)}
+        return out
+
+    def pack_fields(self, filename: str) -> dict:
+        """The stored (pack) values for the overridable catalog fields — the
+        Fix-metadata popup shows these behind each override as the 'revert to
+        pack' reference + the Yours/Pack provenance. Empty strings for a missing
+        song so the popup always has a value to render."""
+        keys = ("title", "artist", "album", "year", "genre")
+        row = self.conn.execute(
+            "SELECT title, artist, album, year, genre FROM songs WHERE filename = ?",
+            (filename,)).fetchone()
+        return {k: ((row[i] or "") if row else "") for i, k in enumerate(keys)}
+
     def set_song_tags(self, filename: str, tags) -> list:
         """Replace ALL of a song's tags with the given set (each normalized;
         blanks + case-dupes dropped). Full-replace so the whole personal-meta
@@ -1225,6 +1341,7 @@ class MetadataDB:
         INSIDE the caller's `meta_db._lock` — must not re-acquire the lock."""
         self.conn.execute("DELETE FROM song_user_meta WHERE filename = ?", (filename,))
         self.conn.execute("DELETE FROM song_tags WHERE filename = ?", (filename,))
+        self.conn.execute("DELETE FROM song_field_override WHERE filename = ?", (filename,))
 
     def batch_user_meta(self, filenames, *, set_difficulty="__keep__",
                         add_tags=None, remove_tags=None) -> int:
@@ -3011,6 +3128,42 @@ class MetadataDB:
                 "JOIN songs s ON s.filename = e.filename GROUP BY e.match_state").fetchall()
         return {r[0]: r[1] for r in rows}
 
+    def enrichment_states_for(self, filenames: list[str]) -> dict:
+        """{filename: match_state} for the given songs — a never-enriched (or
+        unknown) filename is simply absent from the result. Powers the per-tile
+        badges on the "Refresh Metadata" batch: the grid polls only the
+        filenames in its visible window, not the whole library, so a card can
+        animate queued→working→result without a per-song round-trip."""
+        if not filenames:
+            return {}
+        out: dict = {}
+        with self._lock:
+            # Chunk under SQLite's variable limit so a huge visible window (or a
+            # hostile caller) can't overflow the single IN (...) parameter list.
+            for i in range(0, len(filenames), 400):
+                chunk = filenames[i:i + 400]
+                q = ("SELECT filename, match_state FROM song_enrichment "
+                     "WHERE filename IN (%s)" % ",".join("?" * len(chunk)))
+                for fn, st in self.conn.execute(q, chunk).fetchall():
+                    out[fn] = st
+        return out
+
+    def _unmatched_set(self, filenames) -> set:
+        """The subset of `filenames` whose enrichment landed in the 'failed'
+        (no-match) state — feeds the grid's persistent per-card "no match" badge,
+        so the misses stay visible at rest (the batch tile only shows while a
+        refresh runs). Chunked set membership, like favorite_set."""
+        fns = list(filenames)
+        out: set = set()
+        for i in range(0, len(fns), 400):
+            chunk = fns[i:i + 400]
+            if not chunk:
+                break
+            q = ("SELECT filename FROM song_enrichment WHERE match_state = 'failed' "
+                 "AND filename IN (%s)" % ",".join("?" * len(chunk)))
+            out.update(r[0] for r in self.conn.execute(q, chunk).fetchall())
+        return out
+
     def enrichment_song_row(self, filename: str) -> dict | None:
         """The identity fields the matcher/scorer keys on, for one song."""
         row = self.conn.execute(
@@ -4015,6 +4168,20 @@ class MetadataDB:
         fns = [s["filename"] for s in songs]
         udm = self.user_meta_map(fns)
         tgm = self.tags_map(fns)
+        # Enrichment "no match" (failed) set for the page, so a card can show a
+        # persistent "no match" badge — the Refresh-Metadata batch's transient
+        # per-tile state only paints while a pass runs. Cheap set membership like
+        # favs/estd, so the misses stay visible at rest.
+        um = self._unmatched_set(fns)
+        # Per-song display OVERRIDES (Fix-metadata popup, slice 3). "Grid shows
+        # only overrides": the effective cell is the user's override else the
+        # pack value — a matched MusicBrainz canon NEVER silently re-titles a
+        # card (canon lives in the Details drawer + art). Overlaid in Python
+        # over the visible window, keyset-safe exactly like the P4 alias re-label
+        # below: the seek still runs on the raw column (the one overridable
+        # keyset column, title, stashes its raw value for the cursor — see
+        # _sort_title / next_library_cursor).
+        omap = self.overrides_map(fns)
         # Canonical artist at display (P4): re-label the card's artist through the
         # alias override so "ACDC" reads as "AC/DC". Display-only — the row's sort
         # position (raw artist) is untouched, so a card can show a canonical name
@@ -4024,8 +4191,21 @@ class MetadataDB:
         for s in songs:
             s["user_difficulty"] = udm.get(s["filename"])
             s["tags"] = tgm.get(s["filename"], [])
+            s["unmatched"] = s["filename"] in um
             if amap:
                 s["artist"] = amap.get((s.get("artist") or "").lower(), s.get("artist"))
+            # Override wins over the pack AND the alias re-label — it's the user's
+            # explicit per-song choice. Only a non-empty override VALUE replaces a
+            # cell; a lock-only row (value None) leaves the displayed value alone.
+            ov = omap.get(s["filename"])
+            if ov:
+                for field in ("title", "artist", "album", "year"):
+                    cell = ov.get(field)
+                    val = cell.get("value") if cell else None
+                    if val:
+                        if field == "title":
+                            s["_sort_title"] = s["title"]   # raw title, for the keyset cursor
+                        s[field] = val
         # Grouped rows carry the ⚑ N (chart_count) + the work_key from the
         # materialized read-model, so the card can render the "N charts" chip and
         # address the Charts drawer (GET /api/work/{work_key}/charts) without a
@@ -5235,10 +5415,52 @@ def _resolve_dlc_path(dlc: Path, filename: str) -> Path | None:
     check so every filename-bound handler validates before touching the
     filesystem.
 
-    Returns the validated resolved Path, or None if the path is empty
-    or escapes the DLC root.
+    Containment here is LEXICAL (normalize `.`/`..` WITHOUT following
+    symlinks), not `safe_join`'s `.resolve()`-based check — because users
+    commonly mount their song library through a directory JUNCTION/symlink
+    (a library shared across app installs; the desktop app's own mounts).
+    `.resolve()` follows that junction to its real target, sees it sits
+    outside DLC_DIR, and wrongly rejects every song reached through it — the
+    scanner's `rglob` indexes those songs, but art/load then 403/404s (broken
+    covers, unplayable songs). Lexical normalization still rejects the only
+    escapes a `:path` filename can express — `..` traversal and absolute
+    paths — which the traversal tests pin. `safe_join` stays strict (it is
+    the zip-slip / plugin-asset guard, where following a symlink out IS the
+    defense); the loose-folder art handler keeps its own per-file symlink
+    re-check for defence-in-depth.
+
+    Returns the validated Path (not necessarily link-resolved), or None if
+    the filename is empty, contains a NUL, or escapes the DLC root.
     """
-    return safe_join(dlc, filename)
+    if not filename:
+        return None
+    # Backslashes → forward slashes so a Windows-style `..\\x` traversal is
+    # rejected identically on POSIX (mirrors safe_join's normalisation).
+    safe = filename.replace("\\", "/")
+    if "\x00" in safe:
+        return None
+    # Reject drive-letter / absolute paths in BOTH conventions. A POSIX "/x" is
+    # caught by the containment check below (the `/` operator discards `root`),
+    # but a Windows drive-absolute "C:/x" is treated as a relative "C:" dir on
+    # POSIX and would otherwise slip in as `<root>/C:/x` — so the contract must
+    # hold cross-platform (a shared library is reached from either OS).
+    from pathlib import PurePosixPath, PureWindowsPath
+    if (PurePosixPath(safe).is_absolute()
+            or PureWindowsPath(safe).is_absolute()
+            or PureWindowsPath(safe).drive):
+        return None
+    try:
+        root = dlc.resolve()
+        # normpath collapses `.`/`..`/duplicate separators purely lexically —
+        # it never touches the filesystem, so an in-library junction component
+        # is preserved (allowed) while `..`/absolute segments still escape and
+        # get caught by the containment check below.
+        candidate = Path(os.path.normpath(root / safe))
+        if not candidate.is_relative_to(root):
+            return None
+    except (ValueError, OSError):
+        return None
+    return candidate
 
 
 _SMART_TYPE_BASE: dict[str, int] = {"Lead": 0, "Rhythm": 10, "Bass": 20}
@@ -5828,8 +6050,8 @@ _BUILTIN_STARTER_SOURCES: list[tuple[str, str]] = [
         "content/starter/star_spangled_banner.feedpak",
     ),
     (
-        "beethoven-ode_to_joy.feedpak",
-        "content/starter/beethoven-ode_to_joy.feedpak",
+        "the_adicts-ode-to-joy_vst_cover.feedpak",
+        "content/starter/the_adicts-ode-to-joy_vst_cover.feedpak",
     ),
 ]
 _STARTER_SEED_MARKER = ".starter-content-seeded"
@@ -6137,7 +6359,16 @@ def _scan_runner():
 
 _enrich_kick_lock = threading.Lock()
 _enrich_pending_pass = False
-_enrich_status = {"running": False, "processed": 0, "last_pass_at": None}
+# processed = phase-1 stubs stamped this pass (legacy field). total/matched =
+# the phase-2 MATCHING progress the "Refresh Metadata" batch bar reads (the
+# slow, rate-limited part worth a progress readout); current = the song being
+# matched right now, which drives the per-tile "working" badge.
+_enrich_status = {"running": False, "processed": 0, "last_pass_at": None,
+                  "total": 0, "matched": 0, "current": None}
+# Cooperative cancel for the Stop button: the matching/art loops check it
+# between songs (an in-flight ≤1/s lookup can't be interrupted, but no new one
+# is started). Set by /api/enrichment/cancel, cleared when a fresh pass kicks.
+_enrich_cancel = threading.Event()
 # Minimum spacing between EXTERNAL lookups (design: ≤1 req/s + local cache).
 _ENRICH_MIN_INTERVAL = 1.1
 _enrich_last_fetch = 0.0
@@ -6241,13 +6472,31 @@ def _mb_http_get(path: str, params: dict) -> dict | None:
         raise EnrichTransportError("bad JSON from musicbrainz") from e
 
 
-def _mb_search_recordings(artist, title, limit: int = 8) -> list[dict]:
-    """Text search (tier 2–4): denoised Lucene query over /recording."""
+def _mb_search_recordings(artist, title, limit: int = 12) -> list[dict]:
+    """Text search (tier 2–4): denoised Lucene query over /recording. The strict
+    query drops live-only recordings and the ranker rewards the studio take, so a
+    slightly larger default result set gives the re-ranker room to surface the
+    canonical version.
+
+    Runs the strict field-phrase query first (high precision); if it finds
+    nothing, retries ONCE with a loose term query. The strict phrase only matches
+    MusicBrainz's *primary* artist/title, so a recording stored under a non-Latin
+    primary name (大橋純子) whose romanized form ("Junko Ohashi") is only an alias
+    is invisible to it — the loose query searches aliases and rescues it. The
+    retry spends a second throttled request only on a miss; results are re-scored
+    by rank_candidates, so the looser recall doesn't lower match quality
+    (auto-accept still needs the per-field floors)."""
     query = mb_match.build_recording_query(artist, title)
-    if not query:
-        return []
-    body = _mb_http_get("recording", {"query": query, "limit": limit})
-    return mb_match.parse_search_response(body or {})
+    cands: list[dict] = []
+    if query:
+        body = _mb_http_get("recording", {"query": query, "limit": limit})
+        cands = mb_match.parse_search_response(body or {})
+    if not cands:
+        loose = mb_match.build_recording_query(artist, title, loose=True)
+        if loose and loose != query:
+            body = _mb_http_get("recording", {"query": loose, "limit": limit})
+            cands = mb_match.parse_search_response(body or {})
+    return cands
 
 
 # ── AcoustID audio fingerprinting (content-based identification) ──────────────
@@ -6448,6 +6697,78 @@ _MBID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f
 _ISRC_RE = re.compile(r"^[A-Z]{2}[A-Z0-9]{3}[0-9]{7}$")
 
 
+# ── Alias-aware scoring ───────────────────────────────────────────────────────
+# MusicBrainz stores many artists under a non-Latin PRIMARY name (大橋純子) with
+# the romanized form ("Junko Ohashi") only as an ALIAS. A recording search
+# returns the primary name in its artist-credit, never the aliases — so scoring
+# a romanized reference against the primary gives 0 and the match can't confirm.
+# We fetch the artist's aliases (one throttled lookup, process-cached) and hand
+# them to the scorer, but ONLY for a promising near-miss (title already agrees,
+# artist doesn't) so a normal pass spends no extra requests.
+_ALIAS_ENRICH_MAX = 3          # cap alias lookups per song/search (each is ≤1/s)
+_artist_alias_cache: dict[str, list[str]] = {}
+
+
+def _mb_artist_aliases(artist_id: str) -> list[str]:
+    """Romanized/alternate names for a MusicBrainz artist, process-cached (an
+    artist recurs across a whole discography, so a library of one artist costs
+    ONE lookup). Returns [] for an unknown/aliasless artist. Raises
+    EnrichTransportError on a network failure so the caller pauses the pass
+    (nothing is cached on failure → retried next pass)."""
+    aid = str(artist_id or "")
+    if aid in _artist_alias_cache:
+        return _artist_alias_cache[aid]
+    if not _MBID_RE.match(aid):
+        return []
+    body = _mb_http_get(f"artist/{aid}", {"inc": "aliases"})
+    names: list[str] = []
+    if body:
+        sort_name = str(body.get("sort-name") or "").strip()
+        if sort_name:
+            names.append(sort_name)          # often the romanized form for JP artists
+        for al in body.get("aliases") or []:
+            if isinstance(al, dict) and al.get("name"):
+                names.append(str(al["name"]))
+    seen: set[str] = set()
+    out: list[str] = []
+    for n in names:
+        k = n.casefold()
+        if k and k not in seen:
+            seen.add(k)
+            out.append(n)
+    out = out[:12]
+    _artist_alias_cache[aid] = out
+    return out
+
+
+def _alias_enrich(ref: dict, cands: list[dict]) -> None:
+    """Attach `artist_aliases` in place to candidates that look like the
+    non-Latin-primary case — title agrees with the reference but the primary
+    artist doesn't — so the scorer can confirm them via a romanized alias.
+    Bounded by _ALIAS_ENRICH_MAX + the process cache; a no-op when the
+    reference has no artist or nothing is aliasable."""
+    ref_artist = (ref.get("artist") or "").strip()
+    if not ref_artist:
+        return
+    spent = 0
+    for c in cands:
+        if spent >= _ALIAS_ENRICH_MAX:
+            break
+        if not isinstance(c, dict) or c.get("artist_aliases") is not None:
+            continue
+        aid = c.get("artist_id")
+        if not aid:
+            continue
+        # Only spend a lookup on a promising near-miss: the title already
+        # matches, but the primary artist doesn't (that's the alias signature).
+        if mb_match.similarity(ref.get("title"), c.get("title")) < mb_match.AUTO_TITLE_MIN:
+            continue
+        if mb_match.similarity(ref_artist, c.get("artist"), artist=True) >= mb_match.AUTO_ARTIST_MIN:
+            continue
+        c["artist_aliases"] = _mb_artist_aliases(aid)   # cached; attach [] to avoid refetch
+        spent += 1
+
+
 def _manifest_exact_ids(filename: str) -> dict:
     """Optional `mbid`/`isrc` from the pack manifest — the spec's additive
     identity keys. Feature-detected: packs published before that spec
@@ -6767,6 +7088,63 @@ def _enrich_field_filter(cfg: dict):
     return lambda cand: {k: v for k, v in cand.items() if k not in blocked}
 
 
+# Strips a trailing tag parenthetical from a filename stem — "(440Hz)",
+# "(Live)", "(No Lead)", the retune/arrangement noise CDLC names carry.
+_FN_TAG_RE = re.compile(r"\s*\([^)]*\)")
+
+
+def _artist_title_from_filename(filename: str) -> dict | None:
+    """Derive artist + title from the CDLC filename convention
+    'Artist_Song-Title_v1_p.feedpak' — spaces written as hyphens WITHIN a
+    field, underscores separating Artist | Title | version/arrangement. Used
+    ONLY as a match SEED for packs whose own `artist` field is blank (a large
+    slice of community charts): text search needs an artist, and the filename
+    reliably carries it. This never becomes displayed metadata — the shown
+    values still come from the confirmed MusicBrainz match (provenance
+    'matched'), so nothing estimated is presented as author-set; if no match is
+    found, the pack stays exactly as-is. Returns None when the name doesn't fit
+    the convention (so a non-CDLC pack falls through untouched)."""
+    base = filename.replace("\\", "/").rsplit("/", 1)[-1]
+    base = base.rsplit(".", 1)[0]                 # drop the extension
+    base = _FN_TAG_RE.sub("", base).strip()       # drop "(440Hz)" etc.
+    parts = [p for p in base.split("_") if p]
+    if len(parts) < 2:
+        return None
+    artist = parts[0].replace("-", " ").strip()
+    title = parts[1].replace("-", " ").strip()
+    if not artist or not title:
+        return None
+    return {"artist": artist, "title": title}
+
+
+# A per-song LOCK (Fix-metadata popup) → the candidate display keys it
+# suppresses on an AUTOMATIC match. Identity keys (recording/release/artist ids,
+# isrc) are deliberately absent: a locked DISPLAY field still gets matched for
+# art + future re-match, it just isn't re-canonicalized behind the user's back.
+_LOCK_FIELD_TO_CAND = {
+    "artist": ("artist", "artist_sort"),
+    "title": ("title",),
+    "album": ("album",),
+    "year": ("year",),
+    "genre": ("genres",),
+}
+
+
+def _compose_lock_filter(base_filter, locked_fields):
+    """Wrap the pass's global per-field apply-filter with a per-song filter that
+    also strips the song's LOCKED display fields, so an automatic match never
+    re-canonicalizes a field the user pinned. Returns base_filter unchanged when
+    the song has no relevant lock (the common path)."""
+    blocked = {ck for f in locked_fields for ck in _LOCK_FIELD_TO_CAND.get(f, ())}
+    if not blocked:
+        return base_filter
+
+    def lock_filter(cand):
+        c = base_filter(cand) if base_filter else cand
+        return {k: v for k, v in c.items() if k not in blocked}
+    return lock_filter
+
+
 def _enrich_one(row: dict, auto_min: float | None = None, field_filter=None,
                 apply_mask: str = "") -> None:
     """The matcher (P8; replaces P7's no-op). Precedence per design §5:
@@ -6792,6 +7170,14 @@ def _enrich_one(row: dict, auto_min: float | None = None, field_filter=None,
     siblings. Network errors raise EnrichTransportError so the pass pauses
     instead of burning attempts while offline."""
     fn, chash = row["filename"], row["content_hash"]
+    # Respect per-song field LOCKS (Fix-metadata popup): an automatic match must
+    # not re-canonicalize a field the user pinned. Compose the lock filter onto
+    # the pass's global apply-filter — both the cache-copy and text-match auto
+    # paths run their candidate through it. (Review/manual picks bypass the
+    # filter, so confirming a match in the modal is an explicit override.)
+    locked = meta_db.locked_fields(fn)
+    if locked:
+        field_filter = _compose_lock_filter(field_filter, locked)
 
     cached = meta_db.enrichment_cache_lookup(chash, exclude_filename=fn)
     if cached:
@@ -6811,17 +7197,35 @@ def _enrich_one(row: dict, auto_min: float | None = None, field_filter=None,
                                            cand=field_filter(cand) if field_filter else cand)
             return
         # A 404'd mbid (typo'd manifest) falls through to the text tiers.
+    # A pack that left `artist` blank can't be text-matched (search needs an
+    # artist, and the per-field floor rejects a blank one) — so when it's blank,
+    # seed the query/scoring from the filename's Artist_Song convention. Seed
+    # only: fn/chash and the stored row are untouched, and the DISPLAYED values
+    # still come from the confirmed match. The exact-key tiers above don't need
+    # it (mbid/isrc identify without text).
+    ref = row
+    if not (row.get("artist") or "").strip():
+        derived = _artist_title_from_filename(fn)
+        if derived:
+            ref = {**row, **derived}
+
     if ids.get("isrc"):
-        cands = mb_match.rank_candidates(row, _mb_lookup_isrc(ids["isrc"]))
+        cands = mb_match.rank_candidates(ref, _mb_lookup_isrc(ids["isrc"]))
         if cands:
             meta_db.apply_enrichment_match(fn, chash, "matched", source="isrc",
                                            score=1.0, apply_mask=apply_mask,
                                            cand=field_filter(cands[0]) if field_filter else cands[0])
             return
 
-    ranked = mb_match.rank_candidates(row, _mb_search_recordings(row.get("artist"), row.get("title")))
+    cands = _mb_search_recordings(ref.get("artist"), ref.get("title"))
+    # Alias-enrich promising near-misses (title agrees, primary artist doesn't)
+    # so a non-Latin-primary artist can confirm via its romanized alias, then
+    # rank once with the aliases in hand. `ref` carries any filename-derived
+    # artist seed, so alias scoring runs against the searched identity.
+    _alias_enrich(ref, cands)
+    ranked = mb_match.rank_candidates(ref, cands)
     best = ranked[0] if ranked else None
-    tier = mb_match.classify(row, best, best["score"], auto_min=auto_min) if best else "none"
+    tier = mb_match.classify(ref, best, best["score"], auto_min=auto_min) if best else "none"
     if tier == "auto":
         meta_db.apply_enrichment_match(fn, chash, "matched", source="text",
                                        score=best["score"], apply_mask=apply_mask,
@@ -6845,8 +7249,13 @@ def _background_enrich():
     `failed` rows whose backoff has elapsed; a transport failure pauses it
     (state untouched, no attempt burned) and the next kick retries. Offline
     (kill-switch or the test env) skips phase 2 entirely. Never drains in a
-    loop — a dead network would make that spin forever."""
+    loop — a dead network would make that spin forever. Between songs it
+    honours the Stop button's cancel flag (phases 2 and 3), so a long trickle
+    can be halted without waiting for the whole queue to drain."""
     _enrich_status["processed"] = 0
+    _enrich_status["total"] = 0
+    _enrich_status["matched"] = 0
+    _enrich_status["current"] = None
     # User settings gate the BACKGROUND matcher only (the review modal's
     # manual search/fix stays available when it's off); read once per pass,
     # up front so the pending query can honour the per-field apply mask
@@ -6911,11 +7320,17 @@ def _background_enrich():
             continue
         seen_filenames.add(fn)
         queue.append(row)
+    _enrich_status["total"] = len(queue)
     for row in queue:
+        if _enrich_cancel.is_set():
+            log.info("enrichment: pass cancelled by user after %d matched", matched)
+            break
+        _enrich_status["current"] = row.get("filename")
         try:
             _enrich_one(row, auto_min=auto_min, field_filter=field_filter,
                         apply_mask=apply_mask)
             matched += 1
+            _enrich_status["matched"] = matched
         except EnrichTransportError as e:
             log.info("enrichment: network unavailable, pass paused (%s)", e)
             break
@@ -6929,6 +7344,7 @@ def _background_enrich():
                     source="error", bump_attempts=True)
             except Exception:
                 pass
+    _enrich_status["current"] = None
     if mb_on and (pending or retriable):
         log.info("Enrichment pass: %d rows stamped, %d matched", len(pending), matched)
 
@@ -6948,6 +7364,9 @@ def _background_enrich():
         return
     fetched = 0
     for row in art_rows:
+        if _enrich_cancel.is_set():
+            log.info("enrichment: art pass cancelled by user after %d fetched", fetched)
+            break
         try:
             fetched += 1 if _enrich_art_one(row) else 0
         except EnrichTransportError as e:
@@ -6972,6 +7391,10 @@ def _kick_enrich() -> bool:
         if _enrich_status["running"]:
             _enrich_pending_pass = True
             return False
+        # A fresh pass supersedes any prior Stop — clear the flag so the new
+        # pass isn't cancelled the instant it checks (a stale set() from a
+        # cancelled-then-re-kicked run would otherwise abort it immediately).
+        _enrich_cancel.clear()
         _enrich_status["running"] = True
     _enrich_thread = threading.Thread(target=_enrich_runner, daemon=True)
     _enrich_thread.start()
@@ -6986,6 +7409,15 @@ def _enrich_runner():
         except Exception:
             log.exception("background enrichment failed unexpectedly")
         with _enrich_kick_lock:
+            _enrich_status["current"] = None
+            if _enrich_cancel.is_set():
+                # Stop: abandon any coalesced follow-up and clear the flag so the
+                # next kick starts clean. The current pass already broke out of
+                # its loop between songs (see _background_enrich).
+                _enrich_pending_pass = False
+                _enrich_cancel.clear()
+                _enrich_status["running"] = False
+                return
             if not _enrich_pending_pass:
                 _enrich_status["running"] = False
                 return
@@ -7473,6 +7905,13 @@ def enrichment_status():
         "last_pass_at": _enrich_status["last_pass_at"],
         "states": meta_db.enrichment_state_counts(),
         "total_songs": meta_db.count(),
+        # Per-pass matching progress for the "Refresh Metadata" batch bar +
+        # per-tile badges (total = songs queued to match this pass, matched =
+        # done so far, current = the one being matched now).
+        "total": _enrich_status.get("total", 0),
+        "matched": _enrich_status.get("matched", 0),
+        "current": _enrich_status.get("current"),
+        "cancelling": _enrich_cancel.is_set(),
     }
 
 
@@ -7491,12 +7930,72 @@ def api_enrichment_song(filename: str):
 
 @app.post("/api/enrichment/kick")
 def api_enrichment_kick():
-    """The Settings "Match now" button: request an enrichment pass without
-    waiting for a scan to complete. Single-flight + coalescing like every
-    other kick — spamming it queues at most one follow-up pass."""
+    """The Settings "Match now" button AND the library's "Refresh Metadata"
+    button: request an enrichment pass without waiting for a scan to complete.
+    Processes the songs that still need it (unscanned/changed + retriable
+    failures) — already-matched songs are left alone, so on a fully-matched
+    library this is a fast no-op. Single-flight + coalescing like every other
+    kick — spamming it queues at most one follow-up pass."""
     return {"started": _kick_enrich()}
 
 
+@app.post("/api/enrichment/cancel")
+def api_enrichment_cancel():
+    """Stop button on the "Refresh Metadata" batch: signal the running pass to
+    halt after the current song (an in-flight ≤1/s lookup can't be interrupted,
+    but no new one is started) and drop any coalesced follow-up. A no-op when
+    nothing is running."""
+    was_running = _enrich_status["running"]
+    if was_running:
+        _enrich_cancel.set()
+    return {"ok": True, "was_running": was_running}
+
+
+@app.post("/api/enrichment/rematch")
+def api_enrichment_rematch(data: dict = Body(...)):
+    """The library "Refresh Metadata" button: force a fresh re-match of the
+    songs the grid is SHOWING (its visible/filtered window). Resets each to
+    `unscanned` so the next pass re-fetches it from scratch — EXCEPT user-pinned
+    `manual` rows, which are never auto-overwritten (apply_enrichment_match
+    guards that) — then kicks one pass. Scoped to the visible set on purpose:
+    fast (dozens of songs), visible (tiles animate), and it can't blow the whole
+    ≤1/s rate budget on a 1000-song library the way a full re-sweep would.
+    Returns the filenames actually queued so the UI badges exactly those."""
+    raw = (data or {}).get("filenames") or []
+    fns = [str(f) for f in raw if isinstance(f, str)][:500]
+    queued: list[str] = []
+    for fn in fns:
+        song = meta_db.enrichment_song_row(fn)
+        if not song:
+            continue
+        h = meta_db.enrichment_content_hash(
+            song["artist"], song["title"], song["album"], song["duration"])
+        # allow_manual_overwrite=False → a manual pin is left as-is (returns
+        # False), everything else resets to unscanned (returns True).
+        if meta_db.apply_enrichment_match(fn, h, "unscanned",
+                                          allow_manual_overwrite=False):
+            queued.append(fn)
+    started = _kick_enrich() if queued else False
+    return {"queued": queued, "count": len(queued), "started": started}
+
+
+@app.post("/api/enrichment/states")
+def api_enrichment_states(data: dict = Body(...)):
+    """Per-tile match states for the grid's VISIBLE window during a metadata
+    refresh: the client posts the filenames it is showing and gets back each
+    one's match_state (+ the song being matched right now, + whether a pass is
+    running), so a card can animate queued→working→result without a per-song
+    round-trip. Read-only — safe for demo visitors (no network, no mutation)."""
+    raw = (data or {}).get("filenames") or []
+    # Bound the batch: a visible grid window is dozens of cards; cap defensively.
+    fns = [str(f) for f in raw if isinstance(f, str)][:500]
+    return {
+        "states": meta_db.enrichment_states_for(fns),
+        "current": _enrich_status.get("current"),
+        "running": _enrich_status["running"],
+    }
+
+
 @app.post("/api/enrichment/refresh/{filename:path}")
 def api_enrichment_refresh(filename: str):
     """The context menu's "Refresh metadata": reset THIS song's match to
@@ -7592,13 +8091,16 @@ def api_enrichment_pick(filename: str, data: dict = Body(...)):
 
 @app.get("/api/enrichment/search")
 def api_enrichment_search(artist: str = "", title: str = "", limit: int = 8,
-                          filename: str = ""):
+                          filename: str = "", duration: float = 0.0):
     """Manual-search proxy to MusicBrainz (throttled + identified like the
     background matcher — a user typing in the drawer must not sidestep the
     rate limit). `filename` optionally scores results against that song's
     stored identity (year/duration corroboration) instead of just the typed
-    text. Sync route on purpose: FastAPI runs it in the threadpool, so the
-    throttle's sleep never blocks the event loop."""
+    text. `duration` (seconds) lets a caller that HAS the audio but no library
+    row — e.g. the editor's create modal, which holds the master track — pass
+    its length so the studio take ranks above live/extended cuts. Sync route on
+    purpose: FastAPI runs it in the threadpool, so the throttle's sleep never
+    blocks the event loop."""
     if not (artist.strip() or title.strip()):
         raise HTTPException(status_code=400, detail="artist or title required")
     limit = max(1, min(int(limit), 25))
@@ -7612,6 +8114,17 @@ def api_enrichment_search(artist: str = "", title: str = "", limit: int = 8,
         ref = meta_db.enrichment_song_row(filename)
     if ref is None:
         ref = {"artist": artist, "title": title}
+    # A caller-supplied duration corroborates the take even without a library row.
+    if duration and duration > 0 and not ref.get("duration"):
+        ref = dict(ref)
+        ref["duration"] = duration
+    # Alias-enrich so a non-Latin-primary artist (大橋純子) ranks by its
+    # romanized alias against the typed query ("Junko Ohashi") instead of
+    # sinking to the bottom with a 0 artist score.
+    try:
+        _alias_enrich(ref, cands)
+    except EnrichTransportError:
+        pass   # aliases are a ranking nicety here; fall back to primary-name scoring
     return {"candidates": mb_match.rank_candidates(ref, cands)}
 
 
@@ -8350,6 +8863,10 @@ async def list_library(q: str = "", page: int = 0, size: int = 24, sort: str = "
     # The cursor to resume after this page (effective sort folds in dir=desc).
     next_cursor = (next_library_cursor(_effective_keyset_sort(sort, dir), songs[-1])
                    if (is_local and songs) else None)
+    # Drop the private raw-title stash query_page attached for the cursor — it's
+    # an internal keyset detail, not part of the card payload.
+    for s in songs:
+        s.pop("_sort_title", None)
     return {"songs": songs, "total": total, "page": page, "size": size,
             "next_cursor": next_cursor}
 
@@ -8688,6 +9205,60 @@ def put_song_user_meta(filename: str, data: dict):
     return meta_db.get_song_user_meta(key)
 
 
+# Catalog fields the Fix-metadata popup may override/lock — the intersection of
+# "displayable identity" and "safe to correct locally". Guitar/practice facts
+# and personal fields are never overrides.
+_OVERRIDE_FIELDS = frozenset({"title", "artist", "album", "year", "genre"})
+
+
+@app.get("/api/song/{filename:path}/overrides")
+def get_song_overrides(filename: str):
+    """Per-field metadata overrides + locks for one song (Fix-metadata popup):
+    {"overrides": {field: {"value": str|null, "locked": bool}},
+     "pack": {field: str}}. `pack` is the stored value each override sits on top
+    of — the popup's Details tab renders it as the revert-to-pack reference and
+    the Yours/Pack provenance."""
+    key = meta_db._canonical_song_filename(filename)
+    return {"overrides": meta_db.get_song_overrides(key),
+            "pack": meta_db.pack_fields(key)}
+
+
+@app.put("/api/song/{filename:path}/overrides")
+def put_song_overrides(filename: str, data: dict):
+    """Set/clear per-field overrides + locks. Body:
+    `{"overrides": {field: {"value": str|null, "locked": bool}}}`. Only catalog
+    fields (title/artist/album/year/genre) are accepted. A field left with no
+    value and unlocked is removed. Returns the merged override map.
+
+    Clearing rides this PUT (send value:null, locked:false) rather than a DELETE
+    sub-route, because `DELETE /api/song/{filename:path}` already owns every
+    DELETE under /api/song and would shadow it (same reason as tags)."""
+    ov = (data or {}).get("overrides")
+    if not isinstance(ov, dict) or not ov:
+        return JSONResponse({"error": "overrides must be a non-empty object"}, 400)
+    bad = sorted(f for f in ov if f not in _OVERRIDE_FIELDS)
+    if bad:
+        return JSONResponse({"error": "unknown field(s): " + ", ".join(bad)}, 400)
+    key = meta_db._canonical_song_filename(filename)
+    for field, spec in ov.items():
+        if not isinstance(spec, dict):
+            return JSONResponse({"error": f"'{field}' must be an object with value/locked"}, 400)
+        kwargs: dict = {}
+        if "value" in spec:
+            v = spec["value"]
+            if v is None:
+                kwargs["value"] = None
+            elif isinstance(v, (str, int, float)) and not isinstance(v, bool):
+                kwargs["value"] = str(v).strip()[:500]
+            else:
+                return JSONResponse({"error": f"'{field}' value must be a string or null"}, 400)
+        if "locked" in spec:
+            kwargs["locked"] = bool(spec["locked"])
+        if kwargs:
+            meta_db.set_song_override(key, field, **kwargs)
+    return {"overrides": meta_db.get_song_overrides(key)}
+
+
 @app.post("/api/songs/user-meta/batch")
 def batch_song_user_meta(data: dict):
     """Bulk personal-meta edit over a selection — one request instead of N×2
@@ -10097,7 +10668,7 @@ def get_tunings():
 @app.get("/api/settings")
 def get_settings():
     cfg = _load_config(CONFIG_DIR / "config.json")
-    return cfg if cfg is not None else _default_settings()
+    return settings_with_instrument_profiles(cfg if cfg is not None else _default_settings())
 
 
 @app.post("/api/settings")
@@ -10319,6 +10890,38 @@ def save_settings(data: dict):
             else:
                 return {"error": "tuning must be a name (string) or a list of semitone offsets"}
 
+    if "pathway" in data:
+        raw = data["pathway"]
+        if raw is not None:
+            if not isinstance(raw, str) or raw not in PROFILE_PATHWAYS:
+                return {"error": "pathway must be one of songs, practice, learn, studio"}
+            updates["pathway"] = raw
+
+    _profile_patch = None
+    if "instrument_profiles" in data:
+        raw = data["instrument_profiles"]
+        if raw is not None:
+            if not isinstance(raw, dict):
+                return {"error": "instrument_profiles must be an object"}
+            # Validate each PROVIDED profile individually and keep the patch
+            # PARTIAL — /api/settings is a partial-merge endpoint, so updating one
+            # profile must NOT reset the others to defaults. Merged over the
+            # persisted profiles inside the lock below (not via the wholesale
+            # `updates` merge, which would clobber the unspecified ones).
+            _profile_patch = {}
+            for _pid, _praw in raw.items():
+                if _pid not in PROFILE_IDS:
+                    return {"error": f"unknown instrument profile: {_pid}"}
+                _prof, _perr = normalize_instrument_profile(_pid, _praw)
+                if _perr:
+                    return {"error": _perr}
+                _profile_patch[_pid] = _prof
+    if "active_instrument_profile" in data:
+        raw = data["active_instrument_profile"]
+        if raw is not None:
+            if not isinstance(raw, str) or raw not in PROFILE_IDS:
+                return {"error": "active_instrument_profile must be one of guitar-lead, guitar-rhythm, bass"}
+            updates["active_instrument_profile"] = raw
     CONFIG_DIR.mkdir(parents=True, exist_ok=True)
     # Critical section — the read-merge-write must be atomic. FastAPI runs
     # sync handlers in a threadpool, so two concurrent partial POSTs (e.g.
@@ -10335,6 +10938,29 @@ def save_settings(data: dict):
         if cfg is None:
             cfg = _default_settings()
         cfg.update(updates)
+        if _profile_patch is not None:
+            # Merge the validated partial over the persisted profiles so a
+            # single-profile update leaves the others intact (a fresh config
+            # falls back to the built-in defaults for the unspecified ones).
+            _existing, _ = normalize_instrument_profiles(cfg.get("instrument_profiles"))
+            if _existing is None:
+                _existing = {}
+            _existing.update(_profile_patch)
+            cfg["instrument_profiles"] = _existing
+        # Only canonicalize/persist the instrument profiles when this save
+        # actually touches them (or the config already carries them). GET always
+        # virtualizes profiles via settings_with_instrument_profiles, so a save
+        # that doesn't touch instrument settings must stay a plain partial merge
+        # — otherwise an empty (or unrelated) POST would freeze the default
+        # profiles into the on-disk config.
+        _profile_keys = ("instrument", "string_count", "tuning", "reference_pitch",
+                         "pathway", "instrument_profiles", "active_instrument_profile")
+        if "instrument_profiles" in cfg or any(k in updates for k in _profile_keys):
+            try:
+                cfg = apply_flat_instrument_patch_to_profiles(cfg, updates)
+            except ValueError as exc:
+                return {"error": str(exc)}
+            cfg = settings_with_instrument_profiles(cfg)
         _atomic_write_file(config_file, json.dumps(cfg, indent=2).encode("utf-8"))
     return {"message": ". ".join(messages) if messages else "Settings saved"}
 
@@ -10346,7 +10972,8 @@ def save_settings(data: dict):
 _RESETTABLE_SETTINGS_KEYS = frozenset({
     "default_arrangement", "demucs_server_url", "master_difficulty",
     "av_offset_ms", "countdown_before_song", "miss_penalty", "fail_behavior",
-    "reference_pitch", "instrument", "string_count", "tuning",
+    "reference_pitch", "instrument", "string_count", "tuning", "pathway",
+    "instrument_profiles", "active_instrument_profile",
     "achievements_enabled", "use_amp_sims",
 })
 
@@ -10371,6 +10998,16 @@ def reset_settings(data: dict):
         removed = [k for k in keys if k in cfg]
         for k in removed:
             del cfg[k]
+        # `pathway` is mirrored into every instrument profile, so deleting the
+        # flat key alone doesn't reset it — GET re-derives the value from the
+        # active profile. Reset it inside the persisted profiles too (back to the
+        # "songs" default), without disturbing the rest of the instrument config.
+        if "pathway" in keys and isinstance(cfg.get("instrument_profiles"), dict):
+            for prof in cfg["instrument_profiles"].values():
+                if isinstance(prof, dict):
+                    prof["pathway"] = "songs"
+            if "pathway" not in removed:
+                removed.append("pathway")
         _atomic_write_file(config_file, json.dumps(cfg, indent=2).encode("utf-8"))
     return {"message": "Settings reset", "reset": removed}
 
@@ -10462,6 +11099,18 @@ def _validate_server_config_types(cfg: dict) -> str | None:
                     return "server_config.tuning offsets must be ≤8 integers between -12 and 12"
             else:
                 return "server_config.tuning must be a name (string) or a list of semitone offsets"
+    if "pathway" in cfg:
+        v = cfg["pathway"]
+        if v is not None and (not isinstance(v, str) or v not in PROFILE_PATHWAYS):
+            return "server_config.pathway must be one of songs, practice, learn, studio"
+    if "instrument_profiles" in cfg:
+        profiles, error = normalize_instrument_profiles(cfg["instrument_profiles"])
+        if error:
+            return f"server_config.{error}"
+    if "active_instrument_profile" in cfg:
+        v = cfg["active_instrument_profile"]
+        if v is not None and (not isinstance(v, str) or v not in PROFILE_IDS):
+            return "server_config.active_instrument_profile must be one of guitar-lead, guitar-rhythm, bass"
     return None
 
 
@@ -10831,6 +11480,7 @@ def export_settings():
     server_config = _load_config(config_file)
     if server_config is None:
         server_config = _default_settings()
+    server_config = settings_with_instrument_profiles(server_config)
 
     # Snapshot the library DB + custom art FIRST: if the irreplaceable state
     # can't be captured, abort with an error rather than hand back a bundle
@@ -11073,7 +11723,7 @@ def import_settings(bundle: dict):
         with _settings_lock:
             _atomic_write_file(
                 CONFIG_DIR / "config.json",
-                json.dumps(server_config, indent=2).encode("utf-8"),
+                json.dumps(settings_with_instrument_profiles(server_config), indent=2).encode("utf-8"),
             )
     except OSError as e:
         # Phase-1 validation should have caught all foreseeable
@@ -11777,15 +12427,21 @@ def _gap_fill_proposals(cache_key: str, resolved) -> tuple[dict, str]:
         manifest = sloppak_mod.load_manifest(resolved) or {}
     except Exception:
         return {}, "not-sloppak"
+    # A LOCKED field (Fix-metadata popup) is never gap-filled — the user pinned
+    # it away from the matched value, so writing that value to the file would
+    # be exactly the clobber the lock exists to prevent. (The lock field name is
+    # `genre`; the manifest/gap-fill key is `genres`.)
+    locked = meta_db.locked_fields(cache_key)
     out = {}
     album = (row.get("canon_album") or "").strip()
-    if album and _gap_fill_manifest_absent(manifest, "album"):
+    if album and "album" not in locked and _gap_fill_manifest_absent(manifest, "album"):
         out["album"] = album
     year = (row.get("canon_year") or "").strip()
-    if year.isdigit() and int(year) and _gap_fill_manifest_absent(manifest, "year"):
+    if (year.isdigit() and int(year) and "year" not in locked
+            and _gap_fill_manifest_absent(manifest, "year")):
         out["year"] = int(year)
     genres = [str(g) for g in (row.get("genres") or []) if isinstance(g, str) and g.strip()]
-    if genres and _gap_fill_manifest_absent(manifest, "genres"):
+    if genres and "genre" not in locked and _gap_fill_manifest_absent(manifest, "genres"):
         out["genres"] = genres
     # Identity keys (feedpak spec 1.14.0) — written in canonical form only.
     mbid = (row.get("mb_recording_id") or "").strip().lower()

static/app.js

@@ -2758,6 +2758,12 @@ function goFavTreePage(p) {
 // ── Settings ─────────────────────────────────────────────────────────────
 let _defaultArrangement = '';
 
+const INSTRUMENT_PATHWAYS = ['songs', 'practice', 'learn', 'studio'];
+
+function _normalizeInstrumentPathway(value) {
+    return INSTRUMENT_PATHWAYS.includes(value) ? value : 'songs';
+}
+
 function _syncDefaultArrangementSelect(value) {
     const sel = document.getElementById('default-arrangement');
     if (!sel) return;
@@ -3410,6 +3416,8 @@ async function loadSettings() {
     if (dlcEl) dlcEl.value = data.dlc_dir || '';
     _defaultArrangement = data.default_arrangement || '';
     _syncDefaultArrangementSelect(_defaultArrangement);
+    const pathwayEl = document.getElementById('setting-instrument-pathway');
+    if (pathwayEl) pathwayEl.value = _normalizeInstrumentPathway(data.pathway);
     const demucsEl = document.getElementById('demucs-server-url');
     if (demucsEl) demucsEl.value = data.demucs_server_url || '';
     const leftyEl = document.getElementById('setting-lefty');
@@ -3901,6 +3909,18 @@ function persistSetting(key, value) {
     _settingSaveChain = next.catch(() => {});
     return next;
 }
+function setInstrumentPathway(value) {
+    const pathway = _normalizeInstrumentPathway(value);
+    const el = document.getElementById('setting-instrument-pathway');
+    if (el) el.value = pathway;
+    persistSetting('pathway', pathway).then(() => {
+        if (window.v3Badges && typeof window.v3Badges.reload === 'function') {
+            try { window.v3Badges.reload(); } catch (_) { /* noop */ }
+        }
+    });
+}
+
+
 async function _postSetting(key, value) {
     const status = document.getElementById('settings-status');
     try {

static/capabilities/working-tuning.js

@@ -305,7 +305,7 @@
                     return fetch('/api/tunings')
                         .then(function (r) { return r && r.ok ? r.json() : null; })
                         .then(function (t) {
-                            const byName = t && t[key];
+                            const byName = t && ((t.tunings && t.tunings[key]) || t[key]);
                             commit(byName ? _offsetsFromFreqs(byName[s.tuning], byName.Standard) : null);
                         })
                         .catch(function () { commit(null); });

static/v3/badges.js

@@ -21,7 +21,13 @@
     const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
         { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
 
-    const STRING_COUNTS = { guitar: [6, 7, 8], bass: [4, 5] };
+    const STRING_COUNTS = { guitar: [6, 7, 8], bass: [4, 5, 6] };
+    const PATHWAY_OPTIONS = [
+        { id: 'songs', label: 'Songs' },
+        { id: 'practice', label: 'Practice' },
+        { id: 'learn', label: 'Learn' },
+        { id: 'studio', label: 'Studio' },
+    ];
     // Tuning names per instrument key (e.g. 'guitar-6', 'bass-4'), loaded from
     // GET /api/tunings. Falls back to empty arrays until the fetch resolves.
     let _tuningsByKey = {};
@@ -106,7 +112,7 @@
         }
     }
 
-    let settings = { instrument: 'guitar', string_count: 6, tuning: 'Standard', reference_pitch: 440 };
+    let settings = { instrument: 'guitar', string_count: 6, tuning: 'Standard', reference_pitch: 440, pathway: 'songs', instrument_profiles: {}, active_instrument_profile: 'guitar-lead' };
 
     async function loadTunings() {
         try {
@@ -126,6 +132,15 @@
         } catch (_) { /* non-fatal — TUNINGS falls back to empty, dropdown shows nothing */ }
     }
 
+    function pathwayForProfile(profiles, profileId, fallback) {
+        const p = profiles && profiles[profileId];
+        return p && PATHWAY_OPTIONS.some((o) => o.id === p.pathway) ? p.pathway : (fallback || 'songs');
+    }
+
+    function profileIdForInstrument(inst) {
+        return inst === 'bass' ? 'bass' : 'guitar-lead';
+    }
+
     async function loadSettings() {
         try {
             const r = await fetch('/api/settings');
@@ -150,16 +165,34 @@
                 if (typeof s.tuning === 'string') tuning = tunings.includes(s.tuning) ? s.tuning : (tunings[0] || 'Standard');
                 else if (Array.isArray(s.tuning)) tuning = s.tuning;
                 else tuning = tunings[0] || 'Standard';
+                const profiles = s.instrument_profiles && typeof s.instrument_profiles === 'object' ? s.instrument_profiles : {};
+                const pathway = PATHWAY_OPTIONS.some((o) => o.id === s.pathway) ? s.pathway : 'songs';
                 settings = {
                     instrument: instrument,
                     string_count: scValid,
                     tuning: tuning,
                     reference_pitch: Math.min(450, Math.max(430, ref)),
+                    pathway: pathway,
+                    instrument_profiles: profiles,
+                    active_instrument_profile: typeof s.active_instrument_profile === 'string' ? s.active_instrument_profile : profileIdForInstrument(instrument),
                 };
             }
         } catch (e) { /* settings endpoint always present */ }
     }
 
+    function syncLocalProfilePatch(patch) {
+        const profileId = profileIdForInstrument(patch.instrument || settings.instrument);
+        if (!settings.instrument_profiles || typeof settings.instrument_profiles !== 'object') settings.instrument_profiles = {};
+        if (patch.instrument) settings.active_instrument_profile = profileId;
+        const profile = Object.assign({}, settings.instrument_profiles[profileId] || {});
+        let changed = false;
+        if (patch.instrument) { profile.instrument = patch.instrument; changed = true; }
+        if (patch.string_count != null) { profile.string_count = patch.string_count; changed = true; }
+        if (patch.tuning != null) { profile.tuning = patch.tuning; changed = true; }
+        if (patch.reference_pitch != null) { profile.reference_pitch = patch.reference_pitch; changed = true; }
+        if (patch.pathway != null) { profile.pathway = patch.pathway; changed = true; }
+        if (changed) settings.instrument_profiles[profileId] = profile;
+    }
     async function saveSettings(patch) {
         // Only adopt the patch once the server accepts it. /api/settings returns
         // {error: ...} with HTTP 200 on a validation failure, so a rejected
@@ -177,8 +210,9 @@
         } catch (e) { /* non-fatal — leave settings unchanged */ }
         if (!accepted) return false;
         Object.assign(settings, patch);
+        syncLocalProfilePatch(patch);
         if (sm && sm.emit) sm.emit('instrument:changed', {
-            instrument: settings.instrument, stringCount: settings.string_count, tuning: settings.tuning,
+            instrument: settings.instrument, stringCount: settings.string_count, tuning: settings.tuning, pathway: settings.pathway,
         });
         pushToTuner();
         renderTuner(); // reflect new tuning on the tuner card
@@ -424,6 +458,9 @@
             // (picking a named tuning still works and replaces the custom one).
             (typeof settings.tuning === 'string' ? '' : '<option selected disabled>Custom</option>') +
             _tuningsForInstrument(settings.instrument, settings.string_count).map((t) => '<option' + (t === settings.tuning ? ' selected' : '') + '>' + esc(t) + '</option>').join('') + '</select></div>' +
+            '<div><div class="text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1">Pathway</div>' +
+            '<select data-inst-pathway class="w-full bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1.5 text-xs text-fb-text outline-none focus:border-fb-primary">' +
+            PATHWAY_OPTIONS.map((p) => '<option value="' + esc(p.id) + '"' + (p.id === settings.pathway ? ' selected' : '') + '>' + esc(p.label) + '</option>').join('') + '</select></div>' +
             '<div><div class="flex justify-between text-[0.625rem] uppercase tracking-wider text-fb-textDim mb-1"><span>Reference pitch</span><span data-ref-val>' + settings.reference_pitch + ' Hz</span></div>' +
             '<input data-inst-ref type="range" min="430" max="450" step="1" value="' + settings.reference_pitch + '" class="w-full slider-input"></div>' +
             '</div></div>';
@@ -454,6 +491,7 @@
                 instrument: v,
                 string_count: newSc,
                 tuning: tunings.includes(settings.tuning) ? settings.tuning : (tunings[0] || settings.tuning),
+                pathway: pathwayForProfile(settings.instrument_profiles, profileIdForInstrument(v), settings.pathway),
             });
             // Only move the working-tuning context once the switch was actually persisted —
             // otherwise the selector stays on the old instrument while the card shows the
@@ -462,11 +500,21 @@
             renderInstrument(); keepOpen();
         }));
         menu.querySelectorAll('[data-pill="strings"]').forEach((b) => b.addEventListener('click', async () => {
-            await saveSettings({ string_count: Number(b.getAttribute('data-val')) });
-            setWorkingInstrument(settings.instrument, settings.string_count);
+            const newSc = Number(b.getAttribute('data-val'));
+            // Clamp the tuning to one valid for the new string count and post it
+            // alongside string_count — otherwise the backend silently resets a
+            // now-invalid tuning to Standard while this UI keeps showing the old
+            // one (settings/tuner desync). Mirrors the instrument-switch clamp.
+            const tunings = _tuningsForInstrument(settings.instrument, newSc);
+            await saveSettings({
+                string_count: newSc,
+                tuning: tunings.includes(settings.tuning) ? settings.tuning : (tunings[0] || settings.tuning),
+            });
+            setWorkingInstrument(settings.instrument, newSc);
             renderInstrument(); keepOpen();
         }));
         menu.querySelector('[data-inst-tuning]').addEventListener('change', (e) => saveSettings({ tuning: e.target.value }));
+        menu.querySelector('[data-inst-pathway]').addEventListener('change', (e) => saveSettings({ pathway: e.target.value }));
         const ref = menu.querySelector('[data-inst-ref]');
         ref.addEventListener('input', (e) => { menu.querySelector('[data-ref-val]').textContent = e.target.value + ' Hz'; });
         ref.addEventListener('change', (e) => saveSettings({ reference_pitch: Number(e.target.value) }));

static/v3/index.html

@@ -429,6 +429,23 @@
                             </select>
                         </div>
                     </div>
+                    <!-- Instrument pathway -->
+                    <div class="fb-srow">
+                        <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 20l-5.447-2.724A1 1 0 013 16.382V5.618a1 1 0 011.447-.894L9 7m0 13l6-3m-6 3V7m6 10l4.553 2.276A1 1 0 0021 18.382V7.618a1 1 0 00-1.447-.894L15 4m0 13V4m0 0L9 7"/></svg></span>
+                        <div class="fb-srow-main">
+                            <div class="fb-srow-title">Instrument pathway</div>
+                            <div class="fb-srow-desc">Preferred path for the selected instrument. This is remembered per instrument profile.</div>
+                        </div>
+                        <div class="fb-srow-control">
+                            <select id="setting-instrument-pathway" onchange="setInstrumentPathway(this.value)"
+                                class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
+                                <option value="songs">Songs</option>
+                                <option value="practice">Practice</option>
+                                <option value="learn">Learn</option>
+                                <option value="studio">Studio</option>
+                            </select>
+                        </div>
+                    </div>
                     <!-- Arrangement routes (naming mode) -->
                     <div class="fb-srow">
                         <span class="fb-srow-icon"><svg fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 20l-5.447-2.724A1 1 0 013 16.382V5.618a1 1 0 011.447-.894L9 7m0 13l6-3m-6 3V7m6 10l4.553 2.276A1 1 0 0021 18.382V7.618a1 1 0 00-1.447-.894L15 4m0 13V4m0 0L9 7"/></svg></span>

static/v3/match-review.js

@@ -131,7 +131,8 @@
     let _queue = [];
     let _idx = 0;
     let _lastFocus = null;
-    let _single = false;   // Fix-match mode: one song, no queue navigation
+    let _single = false;   // Fix-metadata mode: one song, no queue navigation
+    let _tab = 'details';  // active tab in single mode: details | cover | match
 
     function ensureModal() {
         let m = document.getElementById('v3-match-modal');
@@ -180,14 +181,17 @@
         loadQueue();
     }
 
-    // Fix-match (R2): the same modal for ONE song — the escape hatch for a
-    // wrong (or missing) match, reachable from the card's ⋮ / right-click
-    // menu. No stored candidates are required: the search panel opens
-    // pre-filled, and a pick pins the match exactly like the review flow.
+    // Fix metadata (R2 → popup slice 4): the tabbed per-song editor for ONE
+    // song, reachable from the card's ⋮ / right-click menu. Three tabs —
+    // Details (type + lock the displayed fields), Cover art (launch the picker),
+    // Match (pin a MusicBrainz identity). Opens on Details: for the obscure /
+    // blank-artist packs this exists to fix, typing the right title is the tool,
+    // and Match is the escape hatch when text search can surface a record.
     function fixMatch(song) {
         if (!song || !song.filename) return;
         _lastFocus = document.activeElement;
         _single = true;
+        _tab = 'details';
         _queue = [{
             filename: song.filename, title: song.title || song.filename,
             artist: song.artist || '', album: song.album || '',
@@ -198,10 +202,7 @@
         const m = ensureModal();
         m.classList.remove('hidden');
         document.getElementById('v3-match-overlay')?.classList.remove('hidden');
-        renderCurrent();
-        // Straight to the point: the search panel is why this mode exists.
-        document.getElementById('v3-match-panel')
-            ?.querySelector('[data-mr-search-toggle]')?.click();
+        renderCurrent();   // _single ⇒ renderTabbed()
     }
 
     function closeModal() {
@@ -214,7 +215,7 @@
     }
 
     function nav(step) {
-        if (!_queue.length) return;
+        if (_single || !_queue.length) return;   // single mode has no queue to page
         _idx = Math.min(Math.max(_idx + step, 0), _queue.length - 1);
         renderCurrent();
     }
@@ -302,20 +303,20 @@
             '<span class="text-xs text-fb-textDim shrink-0">' + esc(pct) + '</span></span>' +
             '<span class="block text-xs text-fb-textDim truncate">' + esc(meta) + '</span>' +
             diffChips(song, c) +
+            (_single ? '<span class="block text-xs text-fb-primary pt-1">Use these values →</span>' : '') +
             '</button>';
     }
 
-    function renderCurrent() {
-        const panel = document.getElementById('v3-match-panel');
-        if (!panel) return;
-        if (!_queue.length) { renderDone(); return; }
-        _idx = Math.min(_idx, _queue.length - 1);
-        const song = _queue[_idx];
-        if (song._sel == null) song._sel = 0;
+    // The middle content shared by the queue-review render and the single-song
+    // popup's Match tab: the chart being matched, its candidate list, and the
+    // "search instead" panel. Header + footer differ per surface. When there
+    // are no stored candidates (a manual fix), the search panel opens pre-filled
+    // — searching IS the point in that case.
+    function reviewBodyHtml(song) {
         const sub = [song.artist, song.album, song.year, fmtDur(song.duration)].filter(Boolean).join(' · ');
-
-        panel.innerHTML = headerHtml() +
-            '<div class="p-5 space-y-4 overflow-y-auto v3-scroll">' +
+        const noCands = !(song.candidates || []).length;
+        const prefill = noCands ? [song.artist, song.title].filter(Boolean).join(' – ') : '';
+        return '<div class="p-5 space-y-4 overflow-y-auto v3-scroll min-h-0">' +
             // The chart being matched
             '<div class="flex items-start gap-3">' +
             '<img data-mr-art src="' + esc(artUrl(song)) + '" alt="" loading="lazy" class="w-16 h-16 rounded-lg object-cover bg-fb-card shrink-0">' +
@@ -325,25 +326,27 @@
             '<div class="text-xs text-fb-textDim/70 truncate" title="' + esc(song.filename) + '">' + esc(song.filename) + '</div>' +
             missingChips(song) +
             '</div></div>' +
-            // Candidates (Fix-match mode arrives with none — the search panel
-            // is its whole point, so the empty header is suppressed).
-            ((song.candidates || []).length
-                ? '<div class="space-y-1" role="radiogroup" aria-label="Candidates">' +
+            (noCands
+                ? ''
+                : '<div class="space-y-1" role="radiogroup" aria-label="Candidates">' +
                 '<div class="text-xs font-semibold uppercase tracking-wider text-fb-textDim">Candidates (MusicBrainz)</div>' +
                 song.candidates.map((c, i) => candRowHtml(song, c, i, i === song._sel)).join('') +
-                '</div>'
-                : '') +
-            // Search-instead panel
-            '<div data-mr-search-panel class="hidden space-y-2">' +
+                '</div>') +
+            // Search panel — hidden when candidates exist (a "Search instead…"
+            // toggle reveals it); open + pre-filled when there are none.
+            '<div data-mr-search-panel class="' + (noCands ? '' : 'hidden') + ' space-y-2">' +
             '<div class="flex gap-2">' +
-            '<input data-mr-search-input type="text" class="flex-1 bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-sm text-fb-text outline-none focus:border-fb-primary" placeholder="Artist – Title">' +
+            '<input data-mr-search-input type="text" value="' + esc(prefill) + '" class="flex-1 bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1 text-sm text-fb-text outline-none focus:border-fb-primary" placeholder="Artist – Title">' +
             '<button data-mr-search-go class="text-sm text-fb-primary hover:text-fb-primaryHi border border-fb-primary/40 rounded-md px-3">Search</button></div>' +
             '<div data-mr-search-results class="space-y-1"></div></div>' +
-            '</div>' +
-            // Footer actions. Fix-match mode drops Skip (no queue) and the
-            // accept button when there is nothing to accept — search-result
-            // rows carry their own pick action.
-            '<div class="flex items-center justify-between gap-3 p-5 pt-3 border-t border-fb-border/40 shrink-0">' +
+            '</div>';
+    }
+
+    // Footer actions. Single mode drops Skip / Not-a-match (no queue); the
+    // accept button only shows when there is a stored candidate to accept —
+    // search-result rows carry their own pick action.
+    function footerHtml(song) {
+        return '<div class="flex items-center justify-between gap-3 p-5 pt-3 border-t border-fb-border/40 shrink-0">' +
             '<div class="flex items-center gap-3">' +
             (_single ? '' : '<button data-mr-reject class="text-sm text-fb-textDim hover:text-fb-text">Not a match</button>') +
             '<button data-mr-search-toggle class="text-sm text-fb-textDim hover:text-fb-text">Search instead…</button>' +
@@ -352,57 +355,350 @@
             (_single ? '' : '<button data-mr-skip class="text-sm text-fb-textDim hover:text-fb-text px-3 py-2">Skip</button>') +
             ((song.candidates || []).length ? '<button data-mr-accept class="bg-fb-primary hover:bg-fb-primaryHi text-white px-4 py-2 rounded-md text-sm">Use selected</button>' : '') +
             '</div></div>';
-
-        wireCurrent(panel, song);
     }
 
-    function wireCurrent(panel, song) {
+    function renderCurrent() {
+        const panel = document.getElementById('v3-match-panel');
+        if (!panel) return;
+        if (_single) { renderTabbed(); return; }   // popup: the tabbed shell
+        if (!_queue.length) { renderDone(); return; }
+        _idx = Math.min(_idx, _queue.length - 1);
+        const song = _queue[_idx];
+        if (song._sel == null) song._sel = 0;
+        panel.innerHTML = headerHtml() + reviewBodyHtml(song) + footerHtml(song);
         panel.querySelector('[data-mr-close]')?.addEventListener('click', closeModal);
         panel.querySelector('[data-mr-prev]')?.addEventListener('click', () => nav(-1));
         panel.querySelector('[data-mr-next]')?.addEventListener('click', () => nav(1));
         panel.querySelector('[data-mr-skip]')?.addEventListener('click', () => nav(1));
+        wireReviewBody(panel, song);
+    }
+
+    // Candidate / search / accept-reject wiring shared by the queue render and
+    // the popup's Match tab. Scoped to `root` so the tabbed shell can wire just
+    // its tab body — its close + tab chrome live in the header (wired once by
+    // renderTabbed), so wiring here must NOT touch close/prev/next/skip.
+    function wireReviewBody(root, song) {
         // Art failure → flag + re-render once so the "cover art" chip shows.
-        const img = panel.querySelector('[data-mr-art]');
+        const img = root.querySelector('[data-mr-art]');
         if (img) img.onerror = () => {
             img.style.visibility = 'hidden';
             if (!song._artMissing) { song._artMissing = true; renderCurrent(); }
         };
-        panel.querySelectorAll('[data-mr-cand]').forEach((btn) => {
+        root.querySelectorAll('[data-mr-cand]').forEach((btn) => {
             btn.addEventListener('click', () => {
                 song._sel = Number(btn.getAttribute('data-mr-cand'));
                 renderCurrent();
             });
         });
-        panel.querySelector('[data-mr-accept]')?.addEventListener('click', async () => {
+        root.querySelector('[data-mr-accept]')?.addEventListener('click', async () => {
             const cand = (song.candidates || [])[song._sel || 0];
             if (!cand) return;
             await post('/api/enrichment/review/' + enc(song.filename) + '/accept',
                 { recording_id: cand.recording_id });
             settle(song);
         });
-        panel.querySelector('[data-mr-reject]')?.addEventListener('click', async () => {
+        root.querySelector('[data-mr-reject]')?.addEventListener('click', async () => {
             await post('/api/enrichment/review/' + enc(song.filename) + '/reject');
             settle(song);
         });
-        const sp = panel.querySelector('[data-mr-search-panel]');
-        const input = panel.querySelector('[data-mr-search-input]');
-        panel.querySelector('[data-mr-search-toggle]')?.addEventListener('click', () => {
+        const sp = root.querySelector('[data-mr-search-panel]');
+        const input = root.querySelector('[data-mr-search-input]');
+        root.querySelector('[data-mr-search-toggle]')?.addEventListener('click', () => {
             sp?.classList.toggle('hidden');
             if (sp && !sp.classList.contains('hidden') && input && !input.value) {
                 input.value = [song.artist, song.title].filter(Boolean).join(' – ');
                 input.focus();
             }
         });
-        const go = () => runSearch(panel, song);
-        panel.querySelector('[data-mr-search-go]')?.addEventListener('click', go);
+        const go = () => runSearch(root, song);
+        root.querySelector('[data-mr-search-go]')?.addEventListener('click', go);
         input?.addEventListener('keydown', (e) => { if (e.key === 'Enter') { e.preventDefault(); go(); } });
-        panel.querySelector('[data-mr-identify]')?.addEventListener('click', () => runIdentify(panel, song));
+        // Identify-by-audio (AcoustID, #759) renders its hits into the same
+        // search-results area — scope to `root` (the tab body / panel), not the
+        // out-of-scope `panel` the pre-refactor #759 wiring referenced.
+        root.querySelector('[data-mr-identify]')?.addEventListener('click', () => runIdentify(root, song));
+    }
+
+    // ── Tabbed single-song popup (slice 4) ───────────────────────────────────
+    // Header + tab bar, then the active tab's body. The queue-review render
+    // above is untouched; this is only reached in _single mode.
+    function tabHeaderHtml() {
+        const tab = (id, label) =>
+            '<button data-mr-tab="' + id + '" role="tab" aria-selected="' + (_tab === id ? 'true' : 'false') + '" ' +
+            'class="px-3 py-2 text-sm -mb-px border-b-2 ' + (_tab === id
+                ? 'border-fb-primary text-fb-text'
+                : 'border-transparent text-fb-textDim hover:text-fb-text') + '">' + label + '</button>';
+        return '<div class="flex items-center justify-between gap-3 px-5 pt-4 shrink-0">' +
+            '<h3 class="text-lg font-semibold text-fb-text">Fix metadata</h3>' +
+            '<button data-mr-close class="text-fb-textDim hover:text-fb-text" aria-label="Close">✕</button></div>' +
+            '<div role="tablist" class="flex gap-1 px-4 border-b border-fb-border/40 shrink-0">' +
+            tab('details', 'Details') + tab('cover', 'Cover art') + tab('match', 'Match') + '</div>';
+    }
+
+    function renderTabbed() {
+        const panel = document.getElementById('v3-match-panel');
+        if (!panel) return;
+        const song = _queue[0];
+        if (!song) { closeModal(); return; }
+        panel.innerHTML = tabHeaderHtml() +
+            '<div data-mr-tabbody role="tabpanel" class="flex flex-col min-h-0 flex-1 overflow-hidden"></div>';
+        panel.querySelector('[data-mr-close]')?.addEventListener('click', closeModal);
+        panel.querySelectorAll('[data-mr-tab]').forEach((b) => b.addEventListener('click', () => {
+            const t = b.getAttribute('data-mr-tab');
+            if (t !== _tab) { _tab = t; renderTabbed(); }
+        }));
+        const body = panel.querySelector('[data-mr-tabbody]');
+        if (_tab === 'details') { renderDetailsTab(body, song); }
+        else if (_tab === 'cover') { renderCoverTab(body, song); }
+        else {
+            body.innerHTML = reviewBodyHtml(song) + footerHtml(song);
+            wireReviewBody(body, song);
+            if (!(song.candidates || []).length) body.querySelector('[data-mr-search-input]')?.focus();
+        }
+    }
+
+    // Details tab: type + lock the DISPLAYED fields. Values ride the reversible
+    // override store (GET/PUT /api/song/{fn}/overrides) — never the pack file.
+    // Each field sits on its pack value: editing above the pack makes it an
+    // override ("Yours"); a lock pins it so an auto-match can't recanonicalize
+    // it; revert (↺) drops back to the pack value.
+    const DETAIL_FIELDS = [['title', 'Title'], ['artist', 'Artist'], ['album', 'Album'], ['year', 'Year']];
+
+    async function renderDetailsTab(body, song) {
+        body.innerHTML = '<div class="p-5"><p class="text-sm text-fb-textDim">Loading…</p></div>';
+        let data = { overrides: {}, pack: {} };
+        try {
+            const r = await fetch('/api/song/' + enc(song.filename) + '/overrides');
+            if (r.ok) data = await r.json();
+        } catch (_) { /* offline — fall back to the empty baseline */ }
+        if (!_single || _tab !== 'details') return;   // tab/modal changed while fetching
+        const pack = data.pack || {};
+        const ov = data.overrides || {};
+        const st = {};
+        for (const [f] of DETAIL_FIELDS) {
+            const o = ov[f] || {};
+            st[f] = {
+                pack: pack[f] || '',
+                value: (o.value != null ? o.value : (pack[f] || '')),
+                locked: !!o.locked,
+            };
+        }
+        song._detailsState = st;
+        // Match→Details bridge: a candidate picked with "Use these values" lands
+        // its fields here as the pending (unsaved) input values, shown pre-filled
+        // for review — the grid never adopts a match silently, so the user still
+        // Saves (or Writes to file).
+        const adopted = song._pendingDetails;
+        if (adopted) {
+            for (const [f] of DETAIL_FIELDS) {
+                if (f in adopted) st[f].value = String(adopted[f] || '');
+            }
+            song._pendingDetails = null;
+        }
+        paintDetails(body, song);
+        if (adopted) {
+            const s = body.querySelector('[data-df-status]');
+            if (s) { s.className = 'text-xs leading-relaxed text-fb-textDim'; s.textContent = 'Filled from the match — review, then Save or Write to file.'; }
+        }
+    }
+
+    // Match→Details bridge: adopt a candidate's display fields into the Details
+    // tab (opt-in — never silent). Pin the match too so the art/canon follow,
+    // then land on Details pre-filled for review.
+    async function useTheseValues(song, cand) {
+        if (!cand) return;
+        song._pendingDetails = {
+            title: String(cand.title || ''), artist: String(cand.artist || ''),
+            album: String(cand.album || ''), year: String(cand.year || ''),
+        };
+        try {
+            await post('/api/enrichment/review/' + enc(song.filename) + '/pick', { candidate: cand });
+        } catch (_) { /* pin is best-effort; the values still populate Details */ }
+        try { window.feedBack?.emit('library:changed', { reason: 'match' }); } catch (_) { }
+        _tab = 'details';
+        renderTabbed();
+    }
+
+    function paintDetails(body, song) {
+        const st = song._detailsState;
+        const row = ([f, label]) => {
+            const s = st[f];
+            const isYours = !!(String(s.value).trim() && String(s.value).trim() !== String(s.pack).trim());
+            return '<div class="space-y-1">' +
+                '<div class="flex items-center justify-between">' +
+                '<label class="text-xs font-semibold uppercase tracking-wider text-fb-textDim">' + esc(label) + '</label>' +
+                (isYours
+                    ? '<span class="text-[0.625rem] px-1.5 py-0.5 rounded bg-fb-primary/15 text-fb-primary">Yours</span>'
+                    : '<span class="text-[0.625rem] px-1.5 py-0.5 rounded bg-fb-card text-fb-textDim">Pack</span>') +
+                '</div>' +
+                '<div class="flex items-center gap-2">' +
+                '<input data-df-input="' + f + '" type="text" value="' + esc(s.value) + '" ' +
+                'class="flex-1 bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1.5 text-sm text-fb-text outline-none focus:border-fb-primary" ' +
+                'placeholder="' + esc(s.pack || label) + '">' +
+                '<button data-df-lock="' + f + '" type="button" aria-pressed="' + (s.locked ? 'true' : 'false') + '" ' +
+                'title="' + (s.locked ? 'Locked — auto-match won’t change this field' : 'Lock this field against auto-match') + '" ' +
+                'class="px-2 py-1.5 rounded-md border ' + (s.locked ? 'border-fb-primary text-fb-primary bg-fb-primary/10' : 'border-fb-border/50 text-fb-textDim hover:text-fb-text') + '">' +
+                (s.locked ? '🔒' : '🔓') + '</button>' +
+                '<button data-df-revert="' + f + '" type="button" title="Revert to the pack value" ' +
+                'class="px-2 py-1.5 rounded-md border border-fb-border/50 text-fb-textDim hover:text-fb-text">↺</button>' +
+                '</div></div>';
+        };
+        body.innerHTML =
+            '<div class="p-5 space-y-4 overflow-y-auto v3-scroll min-h-0">' +
+            '<div class="flex items-start gap-3">' +
+            '<img src="' + esc(artUrl(song)) + '" alt="" onerror="this.style.visibility=\'hidden\'" class="w-14 h-14 rounded-lg object-cover bg-fb-card shrink-0">' +
+            '<p class="text-xs text-fb-textDim pt-1"><span class="text-fb-text">Save</span> keeps edits as a reversible library overlay — the song files aren\'t touched. <span class="text-fb-text">Write to file</span> bakes them into the pack itself. Lock a field to keep an auto-match from changing it.</p>' +
+            '</div>' +
+            DETAIL_FIELDS.map(row).join('') +
+            '<p data-df-status class="text-xs leading-relaxed"></p>' +
+            '</div>' +
+            '<div class="flex items-center justify-between gap-2 p-5 pt-3 border-t border-fb-border/40 shrink-0">' +
+            '<button data-df-write type="button" title="Write these values into the song file itself — permanent, survives a full rescan. The rest of the pack is untouched." class="text-sm text-fb-textDim hover:text-fb-text border border-fb-border/50 rounded-md px-3 py-2">Write to file</button>' +
+            '<button data-df-save class="bg-fb-primary hover:bg-fb-primaryHi text-white px-4 py-2 rounded-md text-sm">Save</button>' +
+            '</div>';
+        body.querySelectorAll('[data-df-input]').forEach((inp) => {
+            inp.addEventListener('input', () => { st[inp.getAttribute('data-df-input')].value = inp.value; });
+        });
+        body.querySelectorAll('[data-df-lock]').forEach((b) => {
+            b.addEventListener('click', () => { const f = b.getAttribute('data-df-lock'); st[f].locked = !st[f].locked; paintDetails(body, song); });
+        });
+        body.querySelectorAll('[data-df-revert]').forEach((b) => {
+            b.addEventListener('click', () => { const f = b.getAttribute('data-df-revert'); st[f].value = st[f].pack || ''; st[f].locked = false; paintDetails(body, song); });
+        });
+        body.querySelector('[data-df-save]')?.addEventListener('click', () => saveDetails(body, song));
+        body.querySelector('[data-df-write]')?.addEventListener('click', () => writeToFile(body, song));
+    }
+
+    async function saveDetails(body, song) {
+        const st = song._detailsState;
+        const overrides = {};
+        for (const [f] of DETAIL_FIELDS) {
+            const v = String(st[f].value || '').trim();
+            const p = String(st[f].pack || '').trim();
+            // Only store a value that differs from the pack; equal / blank clears
+            // the override (the server drops a value-less, unlocked row).
+            overrides[f] = { value: (v && v !== p) ? v : null, locked: !!st[f].locked };
+        }
+        const status = body.querySelector('[data-df-status]');
+        const saveBtn = body.querySelector('[data-df-save]');
+        if (saveBtn) saveBtn.disabled = true;
+        let ok = false;
+        try {
+            const r = await fetch('/api/song/' + enc(song.filename) + '/overrides', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ overrides }),
+            });
+            ok = r.ok;
+        } catch (_) { ok = false; }
+        if (saveBtn) saveBtn.disabled = false;
+        if (!ok) {
+            if (status) { status.className = 'text-xs h-4 text-fb-accent'; status.textContent = 'Could not save — try again.'; }
+            return;
+        }
+        // Reflect the new effective values on the in-memory song (keeps the Match
+        // tab header consistent) and repaint the library so the card shows them —
+        // the grid reloads on library:changed (slice 3 overlay does the rest).
+        for (const [f] of DETAIL_FIELDS) {
+            const v = String(st[f].value || '').trim(); const p = String(st[f].pack || '').trim();
+            song[f] = (v && v !== p) ? v : (st[f].pack || '');
+        }
+        try { window.feedBack?.emit('library:changed', { reason: 'override' }); } catch (_) { }
+        if (status) { status.className = 'text-xs h-4 text-fb-good'; status.textContent = 'Saved.'; }
+    }
+
+    // "Write to file" — bake the shown title/artist/album/year INTO the pack
+    // itself (the one action here that touches the file), via the existing
+    // POST /api/song/{fn}/meta (writes the manifest, re-stats, coalesces a
+    // rescan). On a real file write the display overrides for those fields are
+    // now redundant, so clear their VALUES (keeping any locks) and re-render —
+    // the field then reads from the file as "Pack". Loose-folder / unwritable
+    // packs fall back to a DB-only update: we say so and keep the overlay.
+    async function writeToFile(body, song) {
+        const st = song._detailsState;
+        const fields = {};
+        for (const [f] of DETAIL_FIELDS) fields[f] = String(st[f].value || '').trim();
+        const status = body.querySelector('[data-df-status]');
+        const writeBtn = body.querySelector('[data-df-write]');
+        const saveBtn = body.querySelector('[data-df-save]');
+        if (writeBtn) writeBtn.disabled = true;
+        if (saveBtn) saveBtn.disabled = true;
+        if (status) { status.className = 'text-xs leading-relaxed text-fb-textDim'; status.textContent = 'Writing to the song file…'; }
+        let ok = false, persisted = false;
+        try {
+            const r = await fetch('/api/song/' + enc(song.filename) + '/meta', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(fields),
+            });
+            ok = r.ok;
+            const j = await r.json().catch(() => ({}));
+            persisted = !!(j && j.persisted);
+        } catch (_) { ok = false; }
+        if (writeBtn) writeBtn.disabled = false;
+        if (saveBtn) saveBtn.disabled = false;
+        if (!ok) {
+            if (status) { status.className = 'text-xs leading-relaxed text-fb-accent'; status.textContent = 'Could not write to the file — try again.'; }
+            return;
+        }
+        // Keep the in-memory song + grid in step with what was *persisted*, not
+        // the raw input: the server coerces a non-numeric/empty year to "" (see
+        // update_song_meta), so mirror that here or the grid card flashes the
+        // typed text (e.g. "abcd") until the next natural refresh corrects it.
+        const applied = { ...fields };
+        if ('year' in applied) {
+            const yr = /^[+-]?\d+$/.test(applied.year) ? parseInt(applied.year, 10) : 0;
+            applied.year = yr ? String(yr) : '';
+        }
+        for (const [f] of DETAIL_FIELDS) song[f] = applied[f];
+        try { window.feedBack?.emit('library:changed', { reason: 'write' }); } catch (_) { }
+        if (persisted) {
+            const clear = {};
+            for (const [f] of DETAIL_FIELDS) clear[f] = { value: null, locked: !!st[f].locked };
+            try {
+                await fetch('/api/song/' + enc(song.filename) + '/overrides', {
+                    method: 'PUT',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ overrides: clear }),
+                });
+            } catch (_) { /* the file write still succeeded; the overlay just lingers */ }
+            await renderDetailsTab(body, song);   // re-fetch: pack now = written values, overrides cleared
+            const s2 = body.querySelector('[data-df-status]');
+            if (s2) { s2.className = 'text-xs leading-relaxed text-fb-good'; s2.textContent = 'Written to the song file.'; }
+        } else if (status) {
+            status.className = 'text-xs leading-relaxed text-fb-textDim';
+            status.textContent = 'Saved to the library — this pack’s file couldn’t be written, so it may revert on a full rescan.';
+        }
+    }
+
+    // Cover-art tab: the current art + a button that hands off to the shared
+    // cover picker (image-picker.js, its own z-[200] modal). A pick there
+    // refreshes every <img> for this song's art — including this thumbnail — so
+    // there's nothing to wire back.
+    function renderCoverTab(body, song) {
+        body.innerHTML =
+            '<div class="p-5 space-y-4 overflow-y-auto v3-scroll min-h-0 flex flex-col items-center text-center">' +
+            '<img src="' + esc(artUrl(song)) + '" alt="" onerror="this.style.visibility=\'hidden\'" class="w-40 h-40 rounded-xl object-cover bg-fb-card">' +
+            '<p class="text-sm text-fb-textDim max-w-sm">Choose from the Cover Art Archive, paste an image link, or upload your own. Your song files are never changed.</p>' +
+            '<button data-cover-open class="bg-fb-primary hover:bg-fb-primaryHi text-white px-4 py-2 rounded-md text-sm">Choose cover art…</button>' +
+            '</div>';
+        body.querySelector('[data-cover-open]')?.addEventListener('click', () => {
+            if (window.__fbOpenImagePicker) {
+                window.__fbOpenImagePicker({ filename: song.filename, title: song.title || song.filename });
+            }
+        });
     }
 
     // Silent-on-success: the chart just leaves the queue and the next one
     // renders; the last one renders the done state. No toasts, no sounds.
     function settle(song) {
-        if (_single) { closeModal(); return; }   // Fix-match: done means done
+        if (_single) {
+            // Popup Match tab: a pinned identity can change the art/canon — nudge
+            // the grid to repaint (silent otherwise, like the queue flow).
+            try { window.feedBack?.emit('library:changed', { reason: 'match' }); } catch (_) { }
+            closeModal();
+            return;
+        }
         const i = _queue.indexOf(song);
         if (i >= 0) _queue.splice(i, 1);
         if (_idx >= _queue.length) _idx = Math.max(0, _queue.length - 1);
@@ -442,6 +738,7 @@
             btn.addEventListener('click', async () => {
                 const cand = cands[Number(btn.getAttribute('data-mr-cand'))];
                 if (!cand) return;
+                if (_single) { useTheseValues(song, cand); return; }   // popup → adopt into Details
                 await post('/api/enrichment/review/' + enc(song.filename) + '/pick',
                     { candidate: cand });
                 settle(song);
@@ -464,30 +761,37 @@
             status = r.status;
             body = await r.json().catch(() => null);
         } catch (_) { /* falls through to the no-results line */ }
-        // Honest states — never a fake hit.
+        // Honest states — never a fake hit. Each says plainly WHICH outcome this
+        // is, so an empty result reads as "it ran, found nothing" (not "broken")
+        // and points at the manual fallback when there's nothing to pick.
+        const note = (html) => { out.innerHTML = '<p class="text-xs text-fb-textDim leading-relaxed">' + html + '</p>'; };
+        const manual = _single
+            ? ' Try <b class="text-fb-text">Search</b>, or just set the album in <b class="text-fb-text">Details</b> and the cover in <b class="text-fb-text">Cover art</b> by hand.'
+            : ' Try <b class="text-fb-text">Search instead</b>.';
         if (status === 412 || (body && body.needs_setup)) {
-            out.innerHTML = '<p class="text-xs text-fb-textDim">Audio identification is off — enable AcoustID and add a free API key to use it.</p>';
+            note('Audio identification is <b class="text-fb-text">off</b>. Turn it on and add a free AcoustID API key in Settings → Library to use it.');
             return;
         }
         if (status === 404) {
-            out.innerHTML = "<p class=\"text-xs text-fb-textDim\">No full-mix audio to fingerprint for this song.</p>";
+            note('This pack has <b class="text-fb-text">no full mix to fingerprint</b> (it\'s chart-only or stems-only).' + manual);
             return;
         }
         if (status === 503) {
-            out.innerHTML = '<p class="text-xs text-fb-textDim">Audio identification is unavailable right now — try again.</p>';
+            note('Could not run the fingerprint right now — the audio tool or network is unavailable. Try again in a moment.');
             return;
         }
         const cands = (body && body.candidates) || [];
         if (!cands.length) {
-            out.innerHTML = '<p class="text-xs text-fb-textDim">No fingerprint match — try text search.</p>';
+            note('<span class="text-fb-good">✓ Fingerprinted the audio</span> — but AcoustID has <b class="text-fb-text">no match</b> for this exact recording (common for obscure or import tracks).' + manual);
             return;
         }
-        out.innerHTML = '<div class="text-xs font-semibold uppercase tracking-wider text-fb-textDim mb-1">Fingerprint matches (AcoustID)</div>' +
+        out.innerHTML = '<div class="text-xs font-semibold uppercase tracking-wider text-fb-good mb-1">✓ Fingerprint matches (AcoustID)</div>' +
             cands.map((c, i) => candRowHtml(song, c, i, false)).join('');
         out.querySelectorAll('[data-mr-cand]').forEach((btn) => {
             btn.addEventListener('click', async () => {
                 const cand = cands[Number(btn.getAttribute('data-mr-cand'))];
                 if (!cand) return;
+                if (_single) { useTheseValues(song, cand); return; }   // popup → adopt into Details
                 await post('/api/enrichment/review/' + enc(song.filename) + '/pick',
                     { candidate: cand });
                 settle(song);

static/v3/settings.js

@@ -28,7 +28,7 @@
     var RESET_MAP = {
         gameplay: {
             server: ['master_difficulty', 'av_offset_ms', 'miss_penalty',
-                'fail_behavior', 'countdown_before_song', 'default_arrangement'],
+                'fail_behavior', 'countdown_before_song', 'default_arrangement', 'pathway'],
             local: ['lefty', 'autoplayExit', 'showUpNext', 'confirmExitSong', 'arrangementNamingMode', 'countdownBeforeSong'],
             after: function () {
                 // Left-handed is held on the highway object, not re-derived

static/v3/songs.js

@@ -490,6 +490,42 @@
             '<svg class="w-3 h-3" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><circle cx="12" cy="12" r="4"/></svg>' + pct + '%</span>';
     }
 
+    // ── Metadata-refresh per-tile state (the "Refresh Metadata" batch) ─────────
+    // A transient badge painted ONLY while a metadata refresh is running: the
+    // songs actually being (re)matched animate queued → working → done. Keyed by
+    // the card's data-fn (= the local filename the enrichment cache keys on).
+    // Empty for every song outside a refresh, so an idle card is byte-identical
+    // to before (keeps the windowed grid's height math untouched). Honest state
+    // transitions, NOT a fake per-song %: a match is binary (design §11).
+    const _metaTile = {};   // fn -> 'queued' | 'working' | 'done' | 'nochange'
+    // Cards whose enrichment landed 'failed' (from the grid payload) — tracked so
+    // the PERSISTENT "no match" badge survives a batch tile clearing (a
+    // _patchCardEnrich with no flag falls back to this instead of wiping it).
+    // Populated as cards render (enrichBadge is called per card with the flag).
+    const _unmatched = new Set();
+    function enrichBadge(fn, unmatched) {
+        if (unmatched !== undefined) { if (unmatched) _unmatched.add(fn); else _unmatched.delete(fn); }
+        // A live batch tile wins over the resting no-match marker (they never
+        // coexist — the batch clears its tiles when it finishes).
+        const st = _metaTile[fn] || (_unmatched.has(fn) ? 'nomatch' : null);
+        if (!st) return '';
+        const M = {
+            queued:   ['bg-black/60 text-fb-textDim', '• Queued', ''],
+            working:  ['bg-fb-primary text-white', '⟳ Matching…', ''],
+            done:     ['bg-fb-good/90 text-black', '✓ Updated', ''],
+            nochange: ['bg-black/60 text-fb-textDim', '— No match', ''],
+            // Resting indicator: subtle, so a mostly-unmatched library isn't a
+            // wall of loud badges; points at the manual fix.
+            nomatch:  ['bg-black/60 text-fb-textDim', 'No match', 'No metadata match found — right-click to fix it by hand'],
+        };
+        const conf = M[st] || M.queued;
+        // top-10 clears the tuning chip (top-2) in both normal and select mode;
+        // z-20 sits it above the art. Non-interactive so it never eats a click.
+        return '<span class="v3-meta-tile absolute top-10 left-2 z-20 ' + conf[0] +
+            ' text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight pointer-events-none"' +
+            (conf[2] ? ' title="' + conf[2] + '"' : '') + '>' + conf[1] + '</span>';
+    }
+
     // After a song is scored, the badge for that card is stale until the next
     // full render(). Refresh state.accuracy from the server and patch the badge
     // of any currently-rendered card/row in place (grid + tree). `_dirtyScores`
@@ -845,7 +881,7 @@
         return '<div class="group relative" data-fn="' + esc(key) + '" data-letter="' + esc(songBucket(song)) + '" data-library-song="' + esc(songId(song)) + '" data-library-provider="' + esc(state.provider) + '">' +
             '<div class="relative aspect-square rounded-lg overflow-hidden bg-fb-card cursor-pointer' + selRing + '" data-v3-play>' +
             '<img src="' + esc(artUrl(shown)) + '" alt="" loading="lazy" decoding="async" class="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105" onerror="this.style.visibility=\'hidden\'">' +
-            tuning + checkbox + accuracyBadge(key) + fmtBadge(shown) + personalBadges(song) + overlay +
+            tuning + checkbox + accuracyBadge(key) + fmtBadge(shown) + personalBadges(song) + enrichBadge(key, song.unmatched) + overlay +
             '<div class="absolute top-2 right-2 flex gap-1 opacity-0 group-hover:opacity-100 transition">' +
             inlineBtns +
             '<button data-fav data-fav-idle="text-white" title="Favorite" aria-label="Favorite" aria-pressed="' + (fav ? 'true' : 'false') + '" class="w-7 h-7 rounded-full bg-black/50 hover:bg-black/70 flex items-center justify-center text-sm ' + (fav ? 'text-fb-accent' : 'text-white') + '">' + (fav ? '♥' : '♡') + '</button>' +
@@ -913,7 +949,7 @@
             // address the local DB / filesystem). Both openers (⋮ and
             // right-click) share this list, so parity is structural.
             ...(state.provider === 'local' && song.filename ? [
-                { id: '__fixmatch', label: 'Fix match…' },
+                { id: '__fixmatch', label: 'Fix metadata…' },
                 { id: '__cover', label: 'Change cover…' },
                 { id: '__refreshmeta', label: 'Refresh metadata' },
                 { id: '__getinfo', label: 'Get info…' },
@@ -1834,13 +1870,57 @@
             '</div>';
     }
 
-    function _renderCardsRange(start, end) {
-        let html = '';
+    // Signature of the card at absolute index i: real-card vs skeleton, plus the
+    // select-mode it was built under. A change here is the ONLY reason a recycled
+    // node must be rebuilt (a hole filled after a fetch, or select mode toggled) —
+    // otherwise the node is reused as-is across window slides.
+    function _cardSig(i) {
+        return (state.songs[i] ? 'r' : 's') + (state.selectMode ? '1' : '0');
+    }
+
+    function _buildCardNode(i) {
+        const s = state.songs[i];
+        const tmp = document.createElement('div');
+        tmp.innerHTML = s ? songCard(s) : _skeletonCard();
+        const node = tmp.firstElementChild;
+        node.setAttribute('data-idx', String(i));
+        node.setAttribute('data-sig', _cardSig(i));
+        return node;
+    }
+
+    // Reconcile the grid's children to exactly cover [start, end) in ascending
+    // index order, REUSING the card nodes that stay in-window. Sliding the window
+    // one row now mutates only the row that entered/left instead of tearing down +
+    // rebuilding (+ re-wiring) the whole ~60-card window every frame — that
+    // per-slide teardown was the main-thread stall behind the "library skips every
+    // so many scrolls, up or down" report (the stall buffers held-arrow key-repeats
+    // that then flush in a burst). wireCards()'s data-wired guard wires only the
+    // freshly-built nodes.
+    function _syncWindow(grid, start, end) {
+        // Pass 1: drop nodes that left the window, are untagged, or whose content
+        // signature is stale (skeleton→real, or select-mode toggled). What remains
+        // is a reusable, correctly-rendered subset in ascending DOM order.
+        for (const el of Array.from(grid.children)) {
+            const a = el.getAttribute('data-idx');
+            const idx = a == null ? NaN : Number(a);
+            if (!(idx >= start && idx < end) || el.getAttribute('data-sig') !== _cardSig(idx)) {
+                el.remove();
+            }
+        }
+        // Pass 2: walk [start, end) in order, reusing survivors and inserting new
+        // nodes into their correct slot; `ref` tracks the child expected next.
+        const existing = new Map();
+        for (const el of grid.children) existing.set(Number(el.getAttribute('data-idx')), el);
+        let ref = grid.firstChild;
         for (let i = start; i < end; i++) {
-            const s = state.songs[i];
-            html += s ? songCard(s) : _skeletonCard();
+            let node = existing.get(i);
+            if (!node) node = _buildCardNode(i);
+            if (node === ref) {
+                ref = ref.nextSibling;
+            } else {
+                grid.insertBefore(node, ref);
+            }
         }
-        return html;
     }
 
     // Fetch a single OFFSET page into the sparse store. Uses the stage-1 keyset
@@ -1958,7 +2038,7 @@
         }
         if (_closeCardMenu) _closeCardMenu();   // its DOM is about to be replaced
         grid.style.top = (firstRow * rowH) + 'px';
-        grid.innerHTML = _renderCardsRange(start, end);
+        _syncWindow(grid, start, end);   // recycle in-window nodes; only the entering/leaving row rebuilds
         wireCards(grid);
         decorateTuningChips(grid);   // colour tuning chips by working-tuning match (async, feature-detected)
         state.winRange = { start, end };
@@ -3402,7 +3482,13 @@
             // shown by match-review.js (window.__fbMatchReviewChip), which
             // also owns the drawer the click opens.
             '<div class="flex items-baseline gap-3"><p class="text-fb-textDim text-sm" id="v3-songs-count"></p>' +
-            '<button id="v3-songs-match-review" class="hidden text-xs text-fb-primary hover:text-fb-primaryHi border border-fb-primary/40 rounded-full px-2.5 py-0.5"></button></div>' +
+            '<button id="v3-songs-match-review" class="hidden text-xs text-fb-primary hover:text-fb-primaryHi border border-fb-primary/40 rounded-full px-2.5 py-0.5"></button>' +
+            // Batch progress for the Refresh Metadata button (shown only while a
+            // pass runs). A real songs-processed ratio, not a fake per-song %.
+            '<span id="v3-meta-progress" class="hidden items-center gap-2 text-xs text-fb-textDim">' +
+            '<span id="v3-meta-progress-label"></span>' +
+            '<span class="inline-block w-24 rounded-full bg-fb-border/40 overflow-hidden align-middle" style="height:6px"><span id="v3-meta-progress-fill" class="block h-full bg-fb-primary transition-all" style="width:0%"></span></span>' +
+            '</span></div>' +
             '<div class="flex flex-wrap gap-2">' +
             (providers.length > 1 ? '<select id="v3-songs-provider" class="' + ctrl + '">' + provOpts + '</select>' : '') +
             '<select id="v3-songs-artist" class="' + ctrl + ' max-w-[11rem]" aria-label="Artist">' + artistSelectHtml() + '</select>' +
@@ -3413,6 +3499,8 @@
             '<button id="v3-songs-filters" class="relative ' + ctrl + ' flex items-center gap-2">Filters<span id="v3-songs-filter-count" class="hidden bg-fb-primary text-white text-xs rounded-full px-1.5">0</span></button>' +
             '<button id="v3-songs-select" class="' + ctrl + (state.selectMode ? ' bg-fb-primary text-white' : '') + '">Select</button>' +
             '<button id="v3-songs-refresh" title="Refresh library (scan for new songs)" class="' + ctrl + '">⟳ Refresh</button>' +
+            '<button id="v3-songs-refresh-meta" title="Refresh metadata for the songs shown (re-match titles, artwork &amp; more)" class="' + ctrl + '">🏷 Metadata</button>' +
+            '<button id="v3-songs-unmatched" title="Show only songs with no metadata match" class="' + ctrl + ((state.filters.match || []).includes('unmatched') ? ' bg-fb-primary text-white' : '') + '">Unmatched</button>' +
             '<button id="v3-songs-upload" class="' + ctrl + '">Upload</button>' +
             '</div></div></div>' +
             // Practice-aware library home: a repertoire progress meter + a
@@ -3450,6 +3538,7 @@
             state.artist = '';
             state.album = '';
             try { sm.libraryProviders && await sm.libraryProviders.select(state.provider); } catch (err) { /* */ }
+            _updateMetaBtnVisibility();   // enrichment is local-only
             await loadArtistCatalog();
             refreshArtistAlbumSelects();
             reload();
@@ -3479,6 +3568,11 @@
         });
         byId('v3-songs-select').addEventListener('click', () => setSelectMode(!state.selectMode));
         byId('v3-songs-refresh')?.addEventListener('click', refreshLibrary);
+        // Refresh Metadata: local-only, so hide it for remote providers. The
+        // button doubles as its own Stop while a pass runs (see onMetaBtnClick).
+        byId('v3-songs-refresh-meta')?.addEventListener('click', onMetaBtnClick);
+        byId('v3-songs-unmatched')?.addEventListener('click', toggleUnmatchedFilter);
+        _updateMetaBtnVisibility();
         // Reflect a scan already in progress (Settings button or a background
         // pass) on the Refresh button, so its state isn't just tied to clicks here.
         (async () => {
@@ -3488,6 +3582,15 @@
                 if (sd && sd.running) { _setRefreshState(sd); _watchScan({ announce: false }); }
             } catch (e) { /* */ }
         })();
+        // Reflect an enrichment pass already running (Settings "Match now" or a
+        // post-scan background pass) on the Metadata button + bar.
+        (async () => {
+            try {
+                const r = await fetch('/api/enrichment/status');
+                const es = r.ok ? await r.json() : null;
+                if (es && es.running) { _setMetaState(es); _watchEnrich({ announce: false }); }
+            } catch (e) { /* */ }
+        })();
 
         // Capture-phase select-mode guard on each persistent list host. Without
         // it, clicking a card/row (or its arrangement chip) in select mode falls
@@ -3706,6 +3809,215 @@
         }, 1000);
     }
 
+    // ── Refresh Metadata (batch enrichment) from the Songs toolbar ─────────────
+    // The metadata counterpart to ⟳ Refresh (which scans FILES): matches
+    // titles/artist/album/artwork against MusicBrainz for the songs that still
+    // need it — the ambient background matcher, run on demand (a media-server's
+    // "Refresh Metadata" vs "Scan Files"). Mirrors the scan machinery: a 1 Hz
+    // poll of /api/enrichment/status drives the button + batch bar, while
+    // /api/enrichment/states drives per-tile badges on the visible window.
+    // Enrichment is local-only, so the button hides for remote providers.
+    let _metaPoll = null;
+    let _metaRunning = false;
+
+    function _updateMetaBtnVisibility() {
+        const local = state.provider === 'local';   // enrichment + its filter are local-only
+        const btn = document.getElementById('v3-songs-refresh-meta');
+        if (btn) btn.style.display = local ? '' : 'none';
+        const um = document.getElementById('v3-songs-unmatched');
+        if (um) um.style.display = local ? '' : 'none';
+    }
+
+    // Quick "Show unmatched" — the same filter as the drawer's Match → Unmatched,
+    // one click from the toolbar so the no-match pile is reachable right after a
+    // batch. Toggles the button + re-queries the grid.
+    function toggleUnmatchedFilter() {
+        const m = state.filters.match || (state.filters.match = []);
+        const i = m.indexOf('unmatched');
+        const on = i < 0;
+        if (on) m.push('unmatched'); else m.splice(i, 1);
+        const btn = document.getElementById('v3-songs-unmatched');
+        if (btn) { btn.classList.toggle('bg-fb-primary', on); btn.classList.toggle('text-white', on); }
+        reload();
+    }
+
+    // The local filenames the grid is currently SHOWING (data-fn is the local
+    // filename the enrichment cache keys on). The grid is windowed, so this is
+    // the visible slice only — exactly what the per-tile poll should cover.
+    function _visibleLocalFilenames() {
+        const grid = document.getElementById('v3-songs-grid');
+        if (!grid) return [];
+        return [...grid.querySelectorAll('[data-fn]')]
+            .map((el) => el.getAttribute('data-fn')).filter(Boolean);
+    }
+
+    // Set/clear one card's live badge (recycled cards re-derive from _metaTile on
+    // the next paint, so update the map too — mirrors _patchCardFav).
+    function _patchCardEnrich(fn, st) {
+        if (st) _metaTile[fn] = st; else delete _metaTile[fn];
+        const sel = (window.CSS && CSS.escape) ? CSS.escape(fn) : fn;
+        document.querySelectorAll('[data-fn="' + sel + '"] [data-v3-play]').forEach((play) => {
+            const el = play.querySelector('.v3-meta-tile');
+            const html = enrichBadge(fn);
+            if (!html) { if (el) el.remove(); return; }
+            if (el) el.outerHTML = html; else play.insertAdjacentHTML('beforeend', html);
+        });
+    }
+
+    function _clearMetaTiles() {
+        Object.keys(_metaTile).forEach((fn) => { delete _metaTile[fn]; });
+        document.querySelectorAll('.v3-meta-tile').forEach((el) => el.remove());
+        // The persistent "No match" badge derives from _unmatched (not _metaTile),
+        // yet shares the .v3-meta-tile class — so the blanket remove above strips it.
+        // Repaint the resting indicator on any rendered card so a metadata rescan's
+        // tile-clear doesn't silently drop it until the next scroll/re-render.
+        _unmatched.forEach((fn) => {
+            const sel = (window.CSS && CSS.escape) ? CSS.escape(fn) : fn;
+            document.querySelectorAll('[data-fn="' + sel + '"] [data-v3-play]').forEach((play) => {
+                if (play.querySelector('.v3-meta-tile')) return;
+                const html = enrichBadge(fn);
+                if (html) play.insertAdjacentHTML('beforeend', html);
+            });
+        });
+    }
+
+
+    // Drive the button (which doubles as Stop) + the batch bar from a status body.
+    function _setMetaState(es) {
+        const btn = document.getElementById('v3-songs-refresh-meta');
+        const prog = document.getElementById('v3-meta-progress');
+        const fill = document.getElementById('v3-meta-progress-fill');
+        const label = document.getElementById('v3-meta-progress-label');
+        if (!btn) return;
+        const running = !!(es && es.running);
+        _metaRunning = running;
+        if (running) {
+            const total = (es && es.total) || 0, done = (es && es.matched) || 0;
+            const cancelling = !!(es && es.cancelling);
+            btn.textContent = cancelling ? 'Stopping…' : ('⏹ Stop' + (total ? ' · ' + done + '/' + total : ''));
+            btn.disabled = cancelling;
+            btn.classList.toggle('opacity-70', cancelling);
+            btn.title = cancelling ? 'Stopping after the current song…' : 'Stop refreshing metadata';
+            if (prog) {
+                prog.classList.remove('hidden'); prog.classList.add('flex');
+                if (label) label.textContent = total ? ('Matching metadata ' + done + '/' + total) : 'Matching metadata…';
+                // Real songs-processed ratio; a tiny sliver while the queue size
+                // is still being computed (phase 1) so the bar isn't dead-empty.
+                if (fill) fill.style.width = (total ? Math.round((done / total) * 100) : 6) + '%';
+            }
+        } else {
+            btn.textContent = '🏷 Metadata';
+            btn.disabled = false;
+            btn.classList.remove('opacity-70');
+            btn.title = 'Refresh metadata for the songs shown (re-match titles, artwork & more)';
+            if (prog) { prog.classList.add('hidden'); prog.classList.remove('flex'); }
+        }
+    }
+
+    // Completion toast — reuse the shared fbNotify surface (visual-only, so
+    // hearing-safe for free). Honest + never-punishing copy, in-game suppressed.
+    function _metaCompleteToast(es) {
+        const active = document.querySelector('.screen.active');
+        if (active && active.id === 'player') return;
+        if (!window.fbNotify) return;
+        const matched = (es && es.matched) || 0;
+        const msg = matched
+            ? (matched + ' song' + (matched === 1 ? '' : 's') + ' matched')
+            : 'Your library metadata is up to date';
+        try { window.fbNotify.show({ title: 'Metadata refresh complete', message: msg, icon: '🏷️', accent: '#22C55E' }); } catch (e) { /* */ }
+    }
+
+    // Poll enrichment status (button + bar) AND the visible window's per-song
+    // states (tile badges) until the pass finishes. announce:false = we only
+    // attached to a pass we didn't start (no toast unless it actually changed
+    // something).
+    function _watchEnrich(opts) {
+        if (_metaPoll) return;
+        const announce = !opts || opts.announce !== false;
+        let sawRunning = false, ticks = 0, lastStatus = null;
+        _metaPoll = setInterval(async () => {
+            ticks++;
+            let es = null;
+            try { const r = await fetch('/api/enrichment/status'); if (r.ok) es = await r.json(); } catch (e) { /* */ }
+            if (es) { lastStatus = es; _setMetaState(es); if (es.running) sawRunning = true; }
+            // Per-tile badges: only songs we're tracking (seeded 'queued'). A
+            // tile flips to 'working' when it's the current song, then to
+            // 'done' (matched) / 'nochange' (failed) once it leaves unscanned.
+            if (Object.keys(_metaTile).length) {
+                const fns = _visibleLocalFilenames();
+                try {
+                    const r = await fetch('/api/enrichment/states', {
+                        method: 'POST', headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ filenames: fns }),
+                    });
+                    if (r.ok) {
+                        const j = await r.json();
+                        const states = j.states || {}, current = j.current;
+                        fns.forEach((fn) => {
+                            if (!(fn in _metaTile)) return;
+                            if (fn === current) { _patchCardEnrich(fn, 'working'); return; }
+                            const s = states[fn];
+                            if (s && s !== 'unscanned' && s !== 'pending') {
+                                _patchCardEnrich(fn, s === 'failed' ? 'nochange' : 'done');
+                            }
+                        });
+                    }
+                } catch (e) { /* */ }
+            }
+            // Cap at 20 min (a ~1000-song trickle at ≤1/s is ~17 min); a
+            // user-initiated no-op that never saw a running pass ends quickly.
+            const noopDone = announce && !sawRunning && ticks >= 3;
+            if ((sawRunning && es && !es.running) || noopDone || ticks >= 1200) {
+                clearInterval(_metaPoll); _metaPoll = null;
+                _setMetaState(null);
+                const changed = sawRunning && lastStatus && (lastStatus.matched || 0) > 0;
+                if (announce || changed) _metaCompleteToast(lastStatus);
+                // Let the final 'done' badges register, then clear + (if anything
+                // matched) reload so new canonical titles/art show.
+                setTimeout(() => {
+                    _clearMetaTiles();
+                    if (changed && window.feedBack) { try { window.feedBack.emit('library:changed', { reason: 'enrich', matched: lastStatus.matched }); } catch (e) { /* */ } }
+                }, 1600);
+            }
+        }, 1000);
+    }
+
+    // Force a fresh re-match of the songs currently SHOWN (the visible grid
+    // window) — a media-server-style per-view "Refresh Metadata". Resets those
+    // songs and re-fetches, so it's visible even on an already-matched library.
+    // Manual pins are skipped server-side; scoped to the visible set so it's
+    // fast + can't blow the whole rate budget.
+    async function refreshMetadata() {
+        if (_metaRunning || _metaPoll) return;       // already running
+        const fns = _visibleLocalFilenames();
+        _clearMetaTiles();
+        if (!fns.length) { _metaCompleteToast({ matched: 0 }); return; }
+        let queued = [];
+        try {
+            const r = await fetch('/api/enrichment/rematch', {
+                method: 'POST', headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ filenames: fns }),
+            });
+            if (r.ok) queued = (await r.json()).queued || [];
+        } catch (e) { /* offline → nothing queued */ }
+        // Badge exactly what the server queued (everything visible except your
+        // manual pins). Nothing queued = all visible songs are pinned/unknown.
+        queued.forEach((fn) => _patchCardEnrich(fn, 'queued'));
+        if (!queued.length) { _metaCompleteToast({ matched: 0 }); return; }
+        _watchEnrich({ announce: true });
+    }
+
+    async function stopMetadata() {
+        try { await fetch('/api/enrichment/cancel', { method: 'POST' }); } catch (e) { /* */ }
+        _setMetaState({ running: true, cancelling: true });   // optimistic; the poll confirms
+    }
+
+    // The Metadata button toggles role: kick a refresh when idle, Stop when a
+    // pass is running.
+    function onMetaBtnClick() {
+        if (_metaRunning) stopMetadata(); else refreshMetadata();
+    }
+
     // Topbar search drives this screen.
     async function search(q) {
         state.q = q || '';

tests/js/v3_songs_window_recycle.test.js

@@ -0,0 +1,143 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+// Mirror of static/v3/songs.js _cardSig / _buildCardNode / _syncWindow (the
+// windowed-grid recycle path, #636 item 3 follow-up) — keep in sync. Exercised
+// against a minimal DOM shim so the reconcile invariants are covered off-browser:
+//   (1) after every slide the grid's children are exactly [start,end) ascending,
+//   (2) card nodes for indices that stay in-window are REUSED (identity kept) —
+//       i.e. sliding one row never tears down + rebuilds the whole window (the
+//       per-slide stall behind the "skips every so many scrolls" report), and
+//   (3) a select-mode toggle rebuilds the visible window (checkbox/ring change).
+
+let NODE_SEQ = 0;
+function makeNode() {
+    const attrs = {};
+    return {
+        _uid: ++NODE_SEQ,
+        parent: null,
+        getAttribute(k) { return k in attrs ? attrs[k] : null; },
+        setAttribute(k, v) { attrs[k] = String(v); },
+        get nextSibling() {
+            const p = this.parent; if (!p) return null;
+            const i = p._kids.indexOf(this);
+            return i >= 0 && i + 1 < p._kids.length ? p._kids[i + 1] : null;
+        },
+        remove() {
+            const p = this.parent; if (!p) return;
+            const i = p._kids.indexOf(this);
+            if (i >= 0) p._kids.splice(i, 1);
+            this.parent = null;
+        },
+    };
+}
+function makeGrid() {
+    return {
+        _kids: [],
+        get children() { return this._kids.slice(); },
+        get firstChild() { return this._kids[0] || null; },
+        insertBefore(node, ref) {
+            if (node.parent) node.remove();
+            if (ref == null) this._kids.push(node);
+            else { const i = this._kids.indexOf(ref); this._kids.splice(i < 0 ? this._kids.length : i, 0, node); }
+            node.parent = this;
+            return node;
+        },
+    };
+}
+
+// --- state + the three helpers, mirrored from songs.js ---
+const state = { songs: [], selectMode: false };
+for (let i = 0; i < 5000; i++) state.songs[i] = { filename: 'song' + i };
+
+function _cardSig(i) { return (state.songs[i] ? 'r' : 's') + (state.selectMode ? '1' : '0'); }
+function _buildCardNode(i) {
+    const node = makeNode();
+    node.setAttribute('data-idx', String(i));
+    node.setAttribute('data-sig', _cardSig(i));
+    return node;
+}
+function _syncWindow(grid, start, end) {
+    for (const el of Array.from(grid.children)) {
+        const a = el.getAttribute('data-idx');
+        const idx = a == null ? NaN : Number(a);
+        if (!(idx >= start && idx < end) || el.getAttribute('data-sig') !== _cardSig(idx)) el.remove();
+    }
+    const existing = new Map();
+    for (const el of grid.children) existing.set(Number(el.getAttribute('data-idx')), el);
+    let ref = grid.firstChild;
+    for (let i = start; i < end; i++) {
+        let node = existing.get(i);
+        if (!node) node = _buildCardNode(i);
+        if (node === ref) ref = ref.nextSibling;
+        else grid.insertBefore(node, ref);
+    }
+}
+
+const idxOf = (g) => g._kids.map((n) => Number(n.getAttribute('data-idx')));
+const uidOf = (g) => { const m = new Map(); for (const n of g._kids) m.set(Number(n.getAttribute('data-idx')), n._uid); return m; };
+function assertContig(g, start, end) {
+    const a = idxOf(g);
+    assert.strictEqual(a.length, end - start, `len == ${end - start}`);
+    for (let k = 0; k < a.length; k++) assert.strictEqual(a[k], start + k, `child ${k} == ${start + k}`);
+}
+
+const COLS = 6, WIN = 12 * COLS; // 12 rows visible
+
+test('window stays [start,end) contiguous scrolling down, one row at a time', () => {
+    const grid = makeGrid();
+    for (let row = 0; row < 40; row++) {
+        const start = row * COLS;
+        _syncWindow(grid, start, start + WIN);
+        assertContig(grid, start, start + WIN);
+    }
+});
+
+test('in-window card nodes are reused across a slide (no whole-window teardown)', () => {
+    const grid = makeGrid();
+    _syncWindow(grid, 0, WIN);
+    const before = uidOf(grid);
+    _syncWindow(grid, COLS, COLS + WIN); // slide down one row
+    const after = uidOf(grid);
+    let reused = 0, built = 0;
+    for (const [i, uid] of after) (before.get(i) === uid ? reused++ : built++);
+    assert.strictEqual(built, COLS, `only the entering row is built (${COLS}), got ${built}`);
+    assert.strictEqual(reused, WIN - COLS, 'every overlapping card node is reused');
+});
+
+test('scrolling back UP reuses nodes too and keeps order', () => {
+    const grid = makeGrid();
+    for (let row = 0; row < 30; row++) _syncWindow(grid, row * COLS, row * COLS + WIN);
+    let prev = uidOf(grid);
+    for (let row = 29; row >= 0; row--) {
+        const start = row * COLS;
+        _syncWindow(grid, start, start + WIN);
+        assertContig(grid, start, start + WIN);
+        const now = uidOf(grid);
+        for (const [i, uid] of prev) if (i >= start && i < start + WIN) assert.strictEqual(now.get(i), uid, `idx ${i} reused going up`);
+        prev = now;
+    }
+});
+
+test('a select-mode toggle rebuilds the visible window', () => {
+    const grid = makeGrid();
+    const start = 6 * COLS;
+    _syncWindow(grid, start, start + WIN);
+    const before = uidOf(grid);
+    state.selectMode = true;
+    _syncWindow(grid, start, start + WIN);
+    const after = uidOf(grid);
+    let rebuilt = 0;
+    for (const [i, uid] of before) if (after.get(i) !== uid) rebuilt++;
+    assert.strictEqual(rebuilt, WIN, 'select-mode change rebuilds every visible card');
+    assertContig(grid, start, start + WIN);
+    state.selectMode = false;
+});
+
+test('a large jump (rail seek) rebuilds cleanly with no stale survivors', () => {
+    const grid = makeGrid();
+    _syncWindow(grid, 0, WIN);
+    _syncWindow(grid, 1000 * COLS, 1000 * COLS + WIN); // non-overlapping jump
+    assertContig(grid, 1000 * COLS, 1000 * COLS + WIN);
+});

tests/js/working_tuning.test.js

@@ -16,8 +16,8 @@ const { createWindow, ROOT } = require('./capabilities_test_harness');
 const CAPABILITIES_JS = path.join(ROOT, 'static', 'capabilities.js');
 const WORKING_TUNING_JS = path.join(ROOT, 'static', 'capabilities', 'working-tuning.js');
 
-// A /api/tunings-shaped fixture (frequencies at 440), enough to resolve names to offsets.
-const TUNINGS = {
+// Tuning frequency fixture at 440 Hz, enough to resolve names to offsets.
+const TUNING_TABLE = {
     'guitar-6': {
         Standard: [82.41, 110.00, 146.83, 196.00, 246.94, 329.63],
         'Drop D': [73.42, 110.00, 146.83, 196.00, 246.94, 329.63],
@@ -26,6 +26,7 @@ const TUNINGS = {
         Standard: [30.87, 41.20, 55.00, 73.42, 98.00],
     },
 };
+const API_TUNINGS = { referencePitch: 440, tunings: TUNING_TABLE };
 
 function deferred() {
     let resolve;
@@ -159,7 +160,7 @@ test('bare-instrument writes target the current selection, not a hard-coded defa
 test('seed resolves a NAMED tuning to offsets via /api/tunings', async () => {
     const { wt, changes } = loadWorkingTuning({
         '/api/settings': { instrument: 'guitar', string_count: 6, tuning: 'Drop D', reference_pitch: 440 },
-        '/api/tunings': TUNINGS,
+        '/api/tunings': API_TUNINGS,
     });
     await flush();
     const s = wt.get('guitar-6');
@@ -183,7 +184,7 @@ test('boot race: an explicit set() before settings resolve is not clobbered by t
     const settings = deferred();
     const { wt } = loadWorkingTuning({
         '/api/settings': settings.promise,           // held open
-        '/api/tunings': TUNINGS,
+        '/api/tunings': API_TUNINGS,
     });
     // A consumer writes before the seed lands.
     wt.set({ offsets: [-5, -5, -5, -5, -5, -5] }, { instrument: 'guitar-6' });

tests/test_dlc_junction.py

@@ -0,0 +1,92 @@
+"""Unit tests for ``server._resolve_dlc_path`` — the DLC-library containment
+guard.
+
+It must (1) allow a library mounted through a directory JUNCTION/symlink (the
+shared-library-across-installs / desktop-app case that a ``.resolve()``-based
+check wrongly rejected, breaking album art + song load), while (2) still
+rejecting ``..`` traversal and absolute paths — the only escapes a ``:path``
+filename can express. ``safe_join`` stays strict on purpose (zip-slip guard),
+so the contrast is pinned here too.
+"""
+
+import importlib
+import os
+import sys
+
+import pytest
+
+
+@pytest.fixture()
+def server(tmp_path, monkeypatch):
+    (tmp_path / "cfg").mkdir()
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path / "cfg"))
+    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:
+            getattr(sys.modules.get("server"), "_join_background_db_threads", lambda: None)()
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+def _dlc(tmp_path):
+    d = tmp_path / "dlc"
+    d.mkdir()
+    return d
+
+
+# ── still-rejected escapes (the security contract) ────────────────────────────
+
+def test_dotdot_traversal_rejected(server, tmp_path):
+    dlc = _dlc(tmp_path)
+    assert server._resolve_dlc_path(dlc, "../../etc/passwd") is None
+    # a Windows-style backslash traversal is normalised + rejected identically
+    assert server._resolve_dlc_path(dlc, "..\\..\\secret") is None
+    assert server._resolve_dlc_path(dlc, "a/../../b") is None
+
+
+def test_absolute_path_rejected(server, tmp_path):
+    dlc = _dlc(tmp_path)
+    assert server._resolve_dlc_path(dlc, "/etc/passwd") is None
+    assert server._resolve_dlc_path(dlc, "C:/Windows/system32/x") is None
+
+
+def test_empty_and_nul_rejected(server, tmp_path):
+    dlc = _dlc(tmp_path)
+    assert server._resolve_dlc_path(dlc, "") is None
+    assert server._resolve_dlc_path(dlc, "a\x00b") is None
+
+
+# ── allowed: legitimate in-library paths ──────────────────────────────────────
+
+def test_safe_relative_allowed(server, tmp_path):
+    dlc = _dlc(tmp_path)
+    p = server._resolve_dlc_path(dlc, "CDLC/City Pop/song.feedpak")
+    assert p is not None
+    assert p.is_relative_to(dlc.resolve())
+
+
+def test_junction_subfolder_allowed(server, tmp_path):
+    """A library mounted through a directory junction/symlink must resolve —
+    the case that broke album art for Christian's shared city-pop library."""
+    dlc = _dlc(tmp_path)
+    real = tmp_path / "real_library"
+    real.mkdir()
+    (real / "song.feedpak").write_bytes(b"pack")
+    link = dlc / "CDLC"
+    try:
+        os.symlink(real, link, target_is_directory=True)
+    except (OSError, NotImplementedError):
+        pytest.skip("symlink/junction creation not permitted on this host")
+
+    p = server._resolve_dlc_path(dlc, "CDLC/song.feedpak")
+    assert p is not None, "a junctioned library subfolder was wrongly rejected"
+    assert p.exists(), "the resolved path should reach the file through the junction"
+    # Contrast: safe_join stays strict (it .resolve()s and follows the junction
+    # to its real target outside the root), which is correct for its zip-slip
+    # callers but is exactly why _resolve_dlc_path can't reuse it here.
+    assert server.safe_join(dlc, "CDLC/song.feedpak") is None

tests/test_enrichment_plumbing.py

@@ -150,3 +150,152 @@ def test_art_cache_dir_created(server):
     d = server._enrichment_art_dir()
     assert d.is_dir()
     assert d.name == "art_cache"
+
+
+# ── Refresh Metadata batch: per-tile states, progress, Stop ───────────────────
+
+def test_states_for_returns_only_known_filenames(server):
+    _put(server, "a.archive")
+    server._background_enrich()
+    got = server.meta_db.enrichment_states_for(["a.archive", "nope.archive"])
+    assert got == {"a.archive": "unscanned"}          # unknown filename absent
+    assert server.meta_db.enrichment_states_for([]) == {}
+
+
+def test_states_endpoint(client, server):
+    _put(server, "a.archive")
+    _put(server, "b.archive", title="Other")
+    server._background_enrich()
+    body = client.post("/api/enrichment/states",
+                       json={"filenames": ["a.archive", "zzz.missing"]}).json()
+    assert body["states"] == {"a.archive": "unscanned"}
+    assert body["running"] is False
+    assert body["current"] is None
+
+
+def test_status_exposes_progress_fields(client, server):
+    _put(server, "a.archive")
+    server._background_enrich()
+    body = client.get("/api/enrichment/status").json()
+    for k in ("total", "matched", "current", "cancelling"):
+        assert k in body
+    assert body["cancelling"] is False
+
+
+def test_cancel_is_noop_when_idle(client, server):
+    body = client.post("/api/enrichment/cancel").json()
+    assert body == {"ok": True, "was_running": False}
+    # A no-op must not arm the flag (which would then poison the next pass).
+    assert server._enrich_cancel.is_set() is False
+
+
+def test_cancel_flag_halts_matching_loop_between_songs(server, monkeypatch):
+    for i in range(4):
+        _put(server, f"s{i}.archive", title=f"Song {i}")
+    # Force the matcher path on (the test env is offline by default) and stub the
+    # per-song matcher so nothing touches the network — it just trips Stop after
+    # the first song, exactly as the /cancel route would mid-pass.
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    calls = []
+
+    def fake_enrich_one(row, **_kw):
+        calls.append(row["filename"])
+        server._enrich_cancel.set()
+
+    monkeypatch.setattr(server, "_enrich_one", fake_enrich_one)
+    server._enrich_cancel.clear()
+    server._background_enrich()
+    # The loop checks cancel BEFORE each song, so exactly one is processed before
+    # it breaks — not the whole 4-row queue.
+    assert calls == ["s0.archive"]
+    assert server._enrich_status["total"] == 4
+    assert server._enrich_status["matched"] == 1
+
+
+def test_rematch_requeues_visible_but_skips_manual(server, client):
+    _put(server, "a.archive")                       # will be 'matched'
+    _put(server, "b.archive", title="Other")        # will be 'failed'
+    _put(server, "c.archive", title="Pinned")       # will be 'manual' — untouchable
+    server._background_enrich()
+    with server.meta_db._lock:
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state='matched' WHERE filename='a.archive'")
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state='failed' WHERE filename='b.archive'")
+        server.meta_db.conn.execute(
+            "UPDATE song_enrichment SET match_state='manual' WHERE filename='c.archive'")
+        server.meta_db.conn.commit()
+    body = client.post("/api/enrichment/rematch", json={
+        "filenames": ["a.archive", "b.archive", "c.archive", "nope.archive"]}).json()
+    # A per-view refresh re-runs everything shown EXCEPT the manual pin (and an
+    # unknown filename); matched + failed are both re-queued.
+    assert set(body["queued"]) == {"a.archive", "b.archive"}
+    assert body["count"] == 2
+    server._join_background_db_threads()
+    assert server.meta_db.get_enrichment("a.archive")["match_state"] == "unscanned"
+    assert server.meta_db.get_enrichment("b.archive")["match_state"] == "unscanned"
+    assert server.meta_db.get_enrichment("c.archive")["match_state"] == "manual"
+
+
+# ── filename-derived artist/title fallback (blank-artist packs) ───────────────
+
+def test_filename_artist_title_parse(server):
+    f = server._artist_title_from_filename
+    assert f("CDLC/0 - City Pop/Tatsuro-Yamashita_Ride-On-Time_v1_p.feedpak") == \
+        {"artist": "Tatsuro Yamashita", "title": "Ride On Time"}
+    assert f("Anri_Windy-Summer_v1_p.feedpak") == {"artist": "Anri", "title": "Windy Summer"}
+    # a trailing "(440Hz)" retune tag is stripped before parsing
+    assert f("Cindy_Watashitachi-o-Shinjite-Ite_v1_p (440Hz).feedpak") == \
+        {"artist": "Cindy", "title": "Watashitachi o Shinjite Ite"}
+    # doesn't fit the convention → no guess
+    assert f("nounderscore.feedpak") is None
+
+
+def test_blank_artist_seeds_match_from_filename(server, monkeypatch):
+    server.meta_db.put("Tatsuro-Yamashita_Ride-On-Time_v1_p.feedpak", 0, 0, {
+        "title": "Tatsuro-Yamashita_Ride-On-Time_v1_p", "artist": "", "album": "",
+        "duration": 240, "arrangements": [{"name": "Bass", "index": 0}]})
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    monkeypatch.setattr(server, "_manifest_exact_ids", lambda fn: {})
+    seen = {}
+
+    def fake_search(artist, title, limit=8):
+        seen["artist"], seen["title"] = artist, title
+        return []
+
+    monkeypatch.setattr(server, "_mb_search_recordings", fake_search)
+    row = next(r for r in server.meta_db.enrichment_pending()
+               if r["filename"].startswith("Tatsuro"))
+    server._enrich_one(row)
+    # the blank pack artist was replaced by the filename-derived identity for
+    # the search (this is exactly what rescues the 'failed' pile)
+    assert seen == {"artist": "Tatsuro Yamashita", "title": "Ride On Time"}
+
+
+def test_present_artist_is_not_overridden_by_filename(server, monkeypatch):
+    server.meta_db.put("Weird-Filename_x_y.feedpak", 0, 0, {
+        "title": "Real Title", "artist": "Real Artist", "album": "", "duration": 100,
+        "arrangements": [{"name": "Lead", "index": 0}]})
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    monkeypatch.setattr(server, "_manifest_exact_ids", lambda fn: {})
+    seen = {}
+
+    def fake_search(artist, title, limit=8):
+        seen["artist"], seen["title"] = artist, title
+        return []
+
+    monkeypatch.setattr(server, "_mb_search_recordings", fake_search)
+    row = next(r for r in server.meta_db.enrichment_pending()
+               if r["filename"].startswith("Weird"))
+    server._enrich_one(row)
+    # a pack that DOES carry an artist keeps it — the filename is never consulted
+    assert seen == {"artist": "Real Artist", "title": "Real Title"}
+
+
+def test_kick_clears_a_stale_cancel(server):
+    # A cancelled-then-rekicked pass must start clean: _kick_enrich clears the
+    # flag so the fresh pass isn't aborted the instant it checks.
+    server._enrich_cancel.set()
+    server._kick_enrich()
+    server._join_background_db_threads()
+    assert server._enrich_cancel.is_set() is False

tests/test_field_overrides.py

@@ -0,0 +1,232 @@
+"""Tests for the per-field metadata override + lock store (Fix-metadata popup).
+
+A reversible DISPLAY overlay, never written to the pack: filename-keyed, so it
+survives a rescan (never purged by delete_missing) and is dropped only with the
+song (delete_song). Locks pin a field against a later auto-match.
+"""
+
+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:
+            getattr(sys.modules.get("server"), "_join_background_db_threads", lambda: None)()
+            conn.close()
+        sys.modules.pop("server", None)
+
+
+@pytest.fixture()
+def client(server):
+    return TestClient(server.app)
+
+
+def _put(server, fn, **meta):
+    base = {"title": "Song", "artist": "Artist", "album": "", "duration": 100,
+            "arrangements": [{"name": "Lead", "index": 0}]}
+    base.update(meta)
+    server.meta_db.put(fn, 0, 0, base)
+
+
+# ── store semantics ───────────────────────────────────────────────────────────
+
+def test_set_get_and_partial_upsert(server):
+    db = server.meta_db
+    assert db.get_song_overrides("a.archive") == {}
+    db.set_song_override("a.archive", "artist", value="AC/DC")
+    assert db.get_song_overrides("a.archive") == {"artist": {"value": "AC/DC", "locked": False}}
+    # partial: lock without touching the value
+    db.set_song_override("a.archive", "artist", locked=True)
+    assert db.get_song_overrides("a.archive")["artist"] == {"value": "AC/DC", "locked": True}
+    # partial: change the value, keep the lock
+    db.set_song_override("a.archive", "artist", value="AC/DC (fixed)")
+    assert db.get_song_overrides("a.archive")["artist"] == {"value": "AC/DC (fixed)", "locked": True}
+
+
+def test_lock_only_row_persists_without_a_value(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "year", locked=True)
+    # a pure lock (no override value) is a valid, kept row
+    assert db.get_song_overrides("a.archive") == {"year": {"value": None, "locked": True}}
+
+
+def test_empty_and_unlocked_drops_the_row(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "album", value="X", locked=True)
+    db.set_song_override("a.archive", "album", value="", locked=False)
+    assert db.get_song_overrides("a.archive") == {}          # no empty shell
+
+
+def test_clear_one_field_leaves_others(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "title", value="T")
+    db.set_song_override("a.archive", "artist", value="A")
+    db.clear_song_override("a.archive", "title")
+    assert set(db.get_song_overrides("a.archive")) == {"artist"}
+
+
+# ── lifecycle: rescan survival vs explicit delete ─────────────────────────────
+
+def test_rescan_never_purges_overrides_delete_does(server):
+    _put(server, "a.archive")
+    server.meta_db.set_song_override("a.archive", "artist", value="AC/DC", locked=True)
+    server.meta_db.delete_missing(set())                     # file vanished from a scan
+    assert server.meta_db.get_song_overrides("a.archive")["artist"]["value"] == "AC/DC"
+    server.meta_db.purge_song_user_data("a.archive")         # the delete_song purge
+    assert server.meta_db.get_song_overrides("a.archive") == {}
+
+
+def test_overrides_map_batches(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "artist", value="A")
+    db.set_song_override("b.archive", "title", value="B", locked=True)
+    m = db.overrides_map(["a.archive", "b.archive", "missing.archive"])
+    assert m["a.archive"]["artist"]["value"] == "A"
+    assert m["b.archive"]["title"] == {"value": "B", "locked": True}
+    assert "missing.archive" not in m
+    assert db.overrides_map([]) == {}
+
+
+# ── API ───────────────────────────────────────────────────────────────────────
+
+def test_api_put_get_and_clear(client, server):
+    _put(server, "a.archive")
+    r = client.put("/api/song/a.archive/overrides",
+                   json={"overrides": {"artist": {"value": "AC/DC", "locked": True},
+                                       "year": {"value": "1979"}}})
+    assert r.status_code == 200
+    ov = r.json()["overrides"]
+    assert ov["artist"] == {"value": "AC/DC", "locked": True}
+    assert ov["year"] == {"value": "1979", "locked": False}
+    assert client.get("/api/song/a.archive/overrides").json()["overrides"]["artist"]["value"] == "AC/DC"
+    # clear via PUT (value null + unlocked) — DELETE is shadowed by /api/song/{path}
+    client.put("/api/song/a.archive/overrides",
+               json={"overrides": {"artist": {"value": None, "locked": False}}})
+    assert "artist" not in client.get("/api/song/a.archive/overrides").json()["overrides"]
+
+
+def test_api_get_returns_pack_values(client, server):
+    _put(server, "a.archive", title="Pack Title", artist="Pack Artist",
+         album="Pack Album", year="1988")
+    server.meta_db.set_song_override("a.archive", "title", value="Fixed Title")
+    body = client.get("/api/song/a.archive/overrides").json()
+    # the override rides "overrides"; the pack baseline rides "pack" (all 5 fields)
+    assert body["overrides"]["title"]["value"] == "Fixed Title"
+    assert body["pack"] == {"title": "Pack Title", "artist": "Pack Artist",
+                            "album": "Pack Album", "year": "1988", "genre": ""}
+    # a song with no row still gets an all-empty pack (popup always has values)
+    assert client.get("/api/song/ghost.archive/overrides").json()["pack"]["title"] == ""
+
+
+def test_api_rejects_unknown_field(client, server):
+    _put(server, "a.archive")
+    r = client.put("/api/song/a.archive/overrides",
+                   json={"overrides": {"tuning": {"value": "Drop D"}}})
+    assert r.status_code == 400
+    assert "unknown field" in r.json()["error"]
+
+
+# ── lock enforcement (slice 2) ────────────────────────────────────────────────
+
+def test_locked_fields_reader(server):
+    db = server.meta_db
+    db.set_song_override("a.archive", "artist", value="X", locked=True)
+    db.set_song_override("a.archive", "title", value="Y")            # override, not locked
+    db.set_song_override("a.archive", "year", locked=True)           # lock only
+    assert db.locked_fields("a.archive") == {"artist", "year"}
+
+
+def test_compose_lock_filter_strips_locked_cand_keys(server):
+    f = server._compose_lock_filter(None, {"artist", "year"})
+    cand = {"recording_id": "r", "artist": "X", "artist_sort": "X", "title": "T",
+            "year": "1990", "album": "A", "genres": ["rock"]}
+    out = f(cand)
+    # locked display keys stripped (artist maps to artist + artist_sort)…
+    assert not ({"artist", "artist_sort", "year"} & set(out))
+    # …identity + unlocked display fields survive
+    assert out["recording_id"] == "r" and out["title"] == "T" and out["album"] == "A"
+    # no locks → base filter returned unchanged (zero-copy common path)
+    assert server._compose_lock_filter(None, set()) is None
+
+
+# ── display overlay in the grid (slice 3) ─────────────────────────────────────
+# "Grid shows only overrides": the effective cell is the user's override else the
+# pack value. Display-only + keyset-safe — the seek stays on the raw column.
+
+def _grid(server, **kw):
+    songs, _ = server.meta_db.query_page(**kw)
+    return {s["filename"]: s for s in songs}
+
+
+def test_grid_shows_override_value_over_pack(server):
+    _put(server, "a.archive", title="Wrong Title", artist="Wrong",
+         album="Pack Album", year="1999")
+    server.meta_db.set_song_override("a.archive", "title", value="Right Title")
+    server.meta_db.set_song_override("a.archive", "artist", value="Right Artist")
+    server.meta_db.set_song_override("a.archive", "year", value="1979")
+    s = _grid(server)["a.archive"]
+    assert s["title"] == "Right Title"
+    assert s["artist"] == "Right Artist"
+    assert s["year"] == "1979"
+    assert s["album"] == "Pack Album"            # no override → pack value shows
+    assert s["_sort_title"] == "Wrong Title"     # raw title stashed for the cursor
+
+
+def test_grid_ignores_lock_only_override(server):
+    _put(server, "a.archive", title="Pack Title")
+    server.meta_db.set_song_override("a.archive", "title", locked=True)   # lock, no value
+    s = _grid(server)["a.archive"]
+    assert s["title"] == "Pack Title"            # a lock without a value never retitles
+    assert "_sort_title" not in s                # …and stashes nothing
+
+
+def test_override_beats_alias_relabel_for_artist(server):
+    _put(server, "a.archive", artist="ACDC")
+    server.meta_db.set_artist_alias("ACDC", "AC/DC")                 # P4 alias
+    assert _grid(server)["a.archive"]["artist"] == "AC/DC"          # alias applies alone
+    server.meta_db.set_song_override("a.archive", "artist", value="AC-DC (mine)")
+    assert _grid(server)["a.archive"]["artist"] == "AC-DC (mine)"   # override wins over alias
+
+
+def test_route_strips_private_sort_title(client, server):
+    _put(server, "a.archive", title="Pack")
+    server.meta_db.set_song_override("a.archive", "title", value="Shown")
+    row = next(s for s in client.get("/api/library?sort=title").json()["songs"]
+               if s["filename"] == "a.archive")
+    assert row["title"] == "Shown"
+    assert "_sort_title" not in row              # private keyset stash never leaks to the client
+
+
+def test_title_keyset_paging_is_complete_with_overrides(client, server):
+    # Raw titles A/B/C → title-sort order is A, B, C on the RAW column.
+    _put(server, "b.archive", title="B")
+    _put(server, "a.archive", title="A")
+    _put(server, "c.archive", title="C")
+    # Overrides that would reshuffle the order IF the cursor wrongly used the
+    # displayed value — the seek must stay on the raw title, so paging still
+    # covers every row exactly once (no skip/dupe).
+    server.meta_db.set_song_override("a.archive", "title", value="ZZZ")
+    server.meta_db.set_song_override("c.archive", "title", value="AAA")
+    seen, cursor = [], None
+    for _ in range(10):
+        url = "/api/library?sort=title&size=1" + (f"&after={cursor}" if cursor else "")
+        data = client.get(url).json()
+        if not data["songs"]:
+            break
+        seen.append(data["songs"][0]["filename"])
+        cursor = data["next_cursor"]
+        if not cursor:
+            break
+    assert sorted(seen) == ["a.archive", "b.archive", "c.archive"]   # each exactly once

tests/test_gap_fill.py

@@ -110,6 +110,19 @@ def test_preview_excludes_author_set_keys(server, client):
     assert {"genres", "mbid", "isrc"} <= got
 
 
+def test_preview_excludes_locked_fields(server, client):
+    """A field LOCKED in the Fix-metadata popup is never gap-filled — writing
+    the matched value would be exactly the clobber the lock prevents — even
+    though the match has a value and the manifest lacks it."""
+    make_dir_sloppak(server, "a.sloppak")
+    seed_match(server, "a.sloppak")
+    server.meta_db.set_song_override("a.sloppak", "album", locked=True)
+    server.meta_db.set_song_override("a.sloppak", "year", locked=True)
+    got = {m["key"] for m in client.get("/api/song/a.sloppak/gap-fill").json()["missing"]}
+    assert "album" not in got and "year" not in got
+    assert {"genres", "mbid", "isrc"} <= got        # unlocked keys still offered
+
+
 def test_preview_excludes_present_but_empty_keys(server, client):
     """Gap-fill is append-only, so a present-but-empty value (album: '',
     year: 0) is NOT a gap the writer can fill — appending would duplicate the

tests/test_gp2rs_gpx.py

@@ -122,6 +122,79 @@ def test_parse_bcfs_rejects_bad_magic():
         _parse_bcfs(b"NOPE" + b"\x00" * 16)
 
 
+# ── _parse_bcfs container round-trip (GP6 .gpx partial final-sector) ─────────
+
+def _build_bcfs(entries, short_by=0):
+    """Assemble a minimal in-memory BCFS container for _parse_bcfs.
+
+    ``entries`` is ``[(name: bytes, payload: bytes, data_sector: int), ...]``.
+    The directory entry for entry *i* is written to sector ``i + 1``; each
+    entry's payload goes in the sector index it names. ``short_by`` truncates
+    the final buffer by N bytes to emulate a real .gpx's partial trailing
+    sector (the BCFZ-declared decompressed size isn't 0x1000-aligned). Layout
+    mirrors the reader: a 4-byte ``BCFS`` header, then 0x1000-byte sectors,
+    with every value read at ``HDR + sector * 0x1000``.
+    """
+    SECTOR = 0x1000
+    HDR = 4
+    max_sector = max([e[2] for e in entries] + [len(entries)])
+    buf = bytearray(b"BCFS" + b"\x00" * ((max_sector + 1) * SECTOR))
+
+    def put_u32(off, val):
+        struct.pack_into("<I", buf, HDR + off, val)
+
+    for i, (name, payload, data_sector) in enumerate(entries):
+        dir_off = (i + 1) * SECTOR                 # directory entry -> sector i+1
+        put_u32(dir_off + 0x00, 2)                 # entry type: file
+        nm = name[:127]
+        buf[HDR + dir_off + 0x04: HDR + dir_off + 0x04 + len(nm)] = nm
+        put_u32(dir_off + 0x8C, len(payload))      # declared file size
+        put_u32(dir_off + 0x94, data_sector)       # first data-sector pointer
+        put_u32(dir_off + 0x94 + 4, 0)             # chain terminator
+        dpos = HDR + data_sector * SECTOR
+        buf[dpos: dpos + len(payload)] = payload
+    if short_by:
+        del buf[len(buf) - short_by:]
+    return bytes(buf)
+
+
+def test_parse_bcfs_reads_short_final_sector():
+    """The regression: a real .gpx ends a byte short of a full 0x1000 sector,
+    so its last (small) container file lands in a partial trailing sector. The
+    reader must clamp that read, not reject the whole container — rejecting it
+    is what made every GP6 .gpx fail to import with 'sector pointer out of
+    range'."""
+    bcfs = _build_bcfs([(b"score.gpif", b"hello", 2)], short_by=1)
+    assert (len(bcfs) - 4) % 0x1000 == 0x1000 - 1   # final sector is 1 short
+    assert _parse_bcfs(bcfs)["score.gpif"] == b"hello"
+
+
+def test_parse_bcfs_full_sector_round_trip():
+    """A sector-aligned container round-trips unchanged (baseline)."""
+    assert _parse_bcfs(_build_bcfs([(b"misc.xml", b"<x/>", 2)]))["misc.xml"] == b"<x/>"
+
+
+def test_parse_bcfs_multi_file_short_final_sector():
+    """Real-world shape: score.gpif plus small config files, the last one in
+    the partial trailing sector."""
+    out = _parse_bcfs(_build_bcfs([
+        (b"score.gpif", b"<GPIF/>", 3),
+        (b"LayoutConfiguration", b"AB", 4),
+    ], short_by=1))
+    assert out["score.gpif"] == b"<GPIF/>"
+    assert out["LayoutConfiguration"] == b"AB"
+
+
+def test_parse_bcfs_rejects_sector_starting_past_end():
+    """A sector pointer whose *start* is beyond the container is genuinely
+    malformed and must still raise — the clamp tolerates a partial final
+    sector, not arbitrary out-of-range pointers."""
+    bcfs = bytearray(_build_bcfs([(b"x", b"y", 2)]))
+    struct.pack_into("<I", bcfs, 4 + 0x1000 + 0x94, 9999)  # absurd data-sector ptr
+    with pytest.raises(ValueError, match="out of range"):
+        _parse_bcfs(bytes(bcfs))
+
+
 # ── _note_is_tie ────────────────────────────────────────────────────────────
 
 def test_note_is_tie_destination():

tests/test_gp_autosync_warp.py

@@ -0,0 +1,284 @@
+"""Tests for the librosa-free piecewise time-warp helpers in lib/gp_autosync.py
+(bar_start_times / build_warp_anchors / warp_time / warp_song_times /
+gp_has_expandable_repeats) plus refine_sync's pure fallbacks.
+
+Fixture-free, matching tests/test_gp_audio_sync.py: every test drives a pure
+helper with hand-built inputs (in-memory GPIF zips, synthetic sync points,
+hand-rolled Song objects). The librosa-backed sweep inside refine_sync needs
+real audio and is covered by manual validation in the PR.
+"""
+
+import io
+import zipfile
+import xml.etree.ElementTree as ET
+
+import pytest
+
+import gp_autosync as ga
+from gp8_audio_sync import GpSyncData, SyncPoint
+from song import (
+    Anchor,
+    Arrangement,
+    Beat,
+    Chord,
+    HandShape,
+    Note,
+    Phrase,
+    PhraseLevel,
+    Section,
+    Song,
+)
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _gpif_zip(gpif_xml: str) -> bytes:
+    """Build an in-memory .gp container holding the given score.gpif."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as zf:
+        zf.writestr("Content/score.gpif", gpif_xml)
+    return buf.getvalue()
+
+
+def _gpif(tempo_autos: list[tuple[int, float]], bar_sigs: list[str]) -> str:
+    autos = "".join(
+        f"<Automation><Type>Tempo</Type><Bar>{bar}</Bar>"
+        f"<Value>{bpm} 2</Value></Automation>"
+        for bar, bpm in tempo_autos
+    )
+    bars = "".join(f"<MasterBar><Time>{sig}</Time></MasterBar>" for sig in bar_sigs)
+    return (
+        "<GPIF><MasterTrack><Automations>"
+        f"{autos}</Automations></MasterTrack>"
+        f"<MasterBars>{bars}</MasterBars></GPIF>"
+    )
+
+
+def _sp(bar, t, mod=120.0, orig=120.0):
+    return SyncPoint(bar=bar, time_secs=t, modified_tempo=mod, original_tempo=orig)
+
+
+# ── bar_start_times ───────────────────────────────────────────────────────────
+
+def test_bar_start_times_constant_tempo(tmp_path):
+    # 120 BPM, 4/4 → every bar is exactly 2s
+    gp = tmp_path / "song.gp"
+    gp.write_bytes(_gpif_zip(_gpif([(0, 120.0)], ["4/4"] * 4)))
+    assert ga.bar_start_times(str(gp)) == pytest.approx([0.0, 2.0, 4.0, 6.0])
+
+
+def test_bar_start_times_tempo_change_and_meter(tmp_path):
+    # Bar 0-1 at 120 (4/4 → 2s each), bar 2 switches to 60 in 3/4 (3s)
+    gp = tmp_path / "song.gp"
+    gp.write_bytes(
+        _gpif_zip(_gpif([(0, 120.0), (2, 60.0)], ["4/4", "4/4", "3/4", "3/4"]))
+    )
+    assert ga.bar_start_times(str(gp)) == pytest.approx([0.0, 2.0, 4.0, 7.0])
+
+
+# ── build_warp_anchors ────────────────────────────────────────────────────────
+
+def test_build_warp_anchors_maps_bars_to_score_time():
+    bar_starts = [0.0, 2.0, 4.0, 6.0]
+    points = [_sp(0, 1.0), _sp(2, 5.4)]
+    assert ga.build_warp_anchors(points, bar_starts) == [(0.0, 1.0), (4.0, 5.4)]
+
+
+def test_build_warp_anchors_drops_nonmonotonic_and_out_of_range():
+    bar_starts = [0.0, 2.0, 4.0, 6.0]
+    points = [
+        _sp(0, 1.0),
+        _sp(1, 0.5),   # audio time goes backwards — dropped
+        _sp(2, 5.4),
+        _sp(99, 9.9),  # bar out of range — dropped
+    ]
+    assert ga.build_warp_anchors(points, bar_starts) == [(0.0, 1.0), (4.0, 5.4)]
+
+
+def test_build_warp_anchors_drops_implausible_slopes():
+    # 2s score bars. A DTW fold (or a run of monotonicity-clamped refine
+    # points) can produce a near-flat audio segment — slope far below the
+    # 0.2x plausibility floor — which would crush every bar in the span.
+    bar_starts = [float(2 * b) for b in range(11)]
+    points = [
+        _sp(0, 1.0),
+        _sp(4, 9.0),    # slope 1.0 — kept
+        _sp(8, 9.1),    # slope 0.0125 over 8s of score — dropped
+        _sp(10, 21.0),  # slope 1.0 vs the last KEPT anchor — kept
+    ]
+    assert ga.build_warp_anchors(points, bar_starts) == [
+        (0.0, 1.0), (8.0, 9.0), (20.0, 21.0)
+    ]
+
+
+def test_build_warp_anchors_requires_two_points():
+    assert ga.build_warp_anchors([_sp(0, 1.0)], [0.0, 2.0]) == []
+    assert ga.build_warp_anchors([], [0.0, 2.0]) == []
+
+
+# ── warp_time ─────────────────────────────────────────────────────────────────
+
+def test_warp_time_interpolates_between_anchors():
+    anchors = [(0.0, 1.0), (10.0, 21.0)]  # slope 2, offset 1
+    assert ga.warp_time(0.0, anchors) == pytest.approx(1.0)
+    assert ga.warp_time(5.0, anchors) == pytest.approx(11.0)
+    assert ga.warp_time(10.0, anchors) == pytest.approx(21.0)
+
+
+def test_warp_time_piecewise_segments():
+    # First half plays at authored speed, second half at half speed
+    anchors = [(0.0, 0.0), (10.0, 10.0), (20.0, 30.0)]
+    assert ga.warp_time(5.0, anchors) == pytest.approx(5.0)
+    assert ga.warp_time(15.0, anchors) == pytest.approx(20.0)
+
+
+def test_warp_time_extrapolates_with_edge_slopes():
+    anchors = [(10.0, 20.0), (20.0, 40.0)]  # slope 2
+    assert ga.warp_time(5.0, anchors) == pytest.approx(10.0)   # before first
+    assert ga.warp_time(25.0, anchors) == pytest.approx(50.0)  # after last
+
+
+def test_warp_time_preserves_order():
+    anchors = [(0.0, 0.5), (4.0, 4.1), (8.0, 9.3), (12.0, 12.9)]
+    times = [i * 0.37 for i in range(40)]
+    warped = [ga.warp_time(t, anchors) for t in times]
+    assert warped == sorted(warped)
+
+
+# ── warp_song_times ───────────────────────────────────────────────────────────
+
+def _shifted_double(t):
+    return 2.0 * t + 1.0
+
+
+def test_warp_song_times_covers_all_time_fields():
+    song = Song(
+        song_length=100.0,
+        beats=[Beat(time=0.0, measure=1), Beat(time=1.0, measure=-1)],
+        sections=[Section(name="verse", number=1, start_time=10.0)],
+        arrangements=[
+            Arrangement(
+                name="Lead",
+                notes=[Note(time=2.0, string=0, fret=3, sustain=1.0)],
+                chords=[
+                    Chord(
+                        time=4.0,
+                        chord_id=0,
+                        notes=[Note(time=4.0, string=1, fret=2, sustain=0.5)],
+                    )
+                ],
+                anchors=[Anchor(time=6.0, fret=3)],
+                hand_shapes=[HandShape(chord_id=0, start_time=4.0, end_time=5.0)],
+                phrases=[
+                    Phrase(
+                        start_time=0.0,
+                        end_time=8.0,
+                        max_difficulty=0,
+                        levels=[
+                            PhraseLevel(
+                                difficulty=0,
+                                notes=[Note(time=3.0, string=0, fret=0, sustain=2.0)],
+                            )
+                        ],
+                    )
+                ],
+                tones={"base": "clean", "changes": [{"t": 7.0, "name": "lead"}]},
+                tempos=[{"time": 0.0, "bpm": 120.0}],
+            )
+        ],
+    )
+
+    ga.warp_song_times(song, _shifted_double)
+
+    assert song.song_length == pytest.approx(201.0)
+    assert [b.time for b in song.beats] == pytest.approx([1.0, 3.0])
+    assert song.sections[0].start_time == pytest.approx(21.0)
+
+    arr = song.arrangements[0]
+    n = arr.notes[0]
+    assert n.time == pytest.approx(5.0)
+    assert n.sustain == pytest.approx(2.0)  # (2+1)*2+1 - 5
+    ch = arr.chords[0]
+    assert ch.time == pytest.approx(9.0)
+    assert ch.notes[0].time == pytest.approx(9.0)
+    assert ch.notes[0].sustain == pytest.approx(1.0)
+    assert arr.anchors[0].time == pytest.approx(13.0)
+    hs = arr.hand_shapes[0]
+    assert (hs.start_time, hs.end_time) == (pytest.approx(9.0), pytest.approx(11.0))
+    ph = arr.phrases[0]
+    assert (ph.start_time, ph.end_time) == (pytest.approx(1.0), pytest.approx(17.0))
+    assert ph.levels[0].notes[0].time == pytest.approx(7.0)
+    assert ph.levels[0].notes[0].sustain == pytest.approx(4.0)
+    assert arr.tones["changes"][0]["t"] == pytest.approx(15.0)
+    assert arr.tempos[0]["time"] == pytest.approx(1.0)
+
+
+def test_warp_song_times_clamps_negative_sustain():
+    # A non-monotonic warp callable must not produce negative sustains
+    song = Song(arrangements=[
+        Arrangement(name="Lead",
+                    notes=[Note(time=1.0, string=0, fret=0, sustain=1.0)])
+    ])
+    ga.warp_song_times(song, lambda t: 5.0 - t)  # decreasing map
+    assert song.arrangements[0].notes[0].sustain == 0.0
+
+
+# ── gp_has_expandable_repeats ─────────────────────────────────────────────────
+
+def test_gpif_files_never_expand_repeats(tmp_path):
+    # GPIF conversion is single-pass as-written, so .gp/.gpx are always False
+    gp = tmp_path / "song.gp"
+    gp.write_bytes(_gpif_zip(_gpif([(0, 120.0)], ["4/4"])))
+    assert ga.gp_has_expandable_repeats(str(gp)) is False
+
+
+def test_gp345_unparseable_returns_false(tmp_path):
+    bad = tmp_path / "song.gp5"
+    bad.write_bytes(b"not a real gp5 file")
+    assert ga.gp_has_expandable_repeats(str(bad)) is False
+
+
+def test_gp345_repeats_detected(tmp_path):
+    guitarpro = pytest.importorskip("guitarpro")
+    song = guitarpro.models.Song()
+    track = guitarpro.models.Track(song)
+    song.tracks = [track]
+    # Bar 2 of 3 opens a repeat
+    for _ in range(2):
+        header = guitarpro.models.MeasureHeader()
+        song.addMeasureHeader(header)
+    song.measureHeaders[1].isRepeatOpen = True
+    for header in song.measureHeaders:
+        track.measures.append(guitarpro.models.Measure(track, header))
+    path = tmp_path / "repeat.gp5"
+    guitarpro.write(song, str(path))
+    assert ga.gp_has_expandable_repeats(str(path)) is True
+
+
+def test_gp345_plain_song_no_repeats(tmp_path):
+    guitarpro = pytest.importorskip("guitarpro")
+    song = guitarpro.models.Song()
+    track = guitarpro.models.Track(song)
+    song.tracks = [track]
+    for _ in range(2):
+        header = guitarpro.models.MeasureHeader()
+        song.addMeasureHeader(header)
+    for header in song.measureHeaders:
+        track.measures.append(guitarpro.models.Measure(track, header))
+    path = tmp_path / "plain.gp5"
+    guitarpro.write(song, str(path))
+    assert ga.gp_has_expandable_repeats(str(path)) is False
+
+
+# ── refine_sync pure fallbacks ────────────────────────────────────────────────
+
+def test_refine_sync_empty_points_returns_input():
+    sync = GpSyncData(audio_offset=0.0, audio_asset_id="", sync_points=[])
+    assert ga.refine_sync(sync, "/nonexistent.ogg") is sync
+
+
+def test_refine_sync_single_point_returns_input():
+    # One point → fewer than 2 warp anchors → unchanged, no audio load
+    sync = GpSyncData(audio_offset=-1.0, audio_asset_id="",
+                      sync_points=[_sp(0, 1.0)])
+    assert ga.refine_sync(sync, "/nonexistent.ogg") is sync

tests/test_library_filters.py

@@ -614,3 +614,16 @@ def test_artist_filter_is_case_insensitive(client, seeded):
     data = _get(client, artist="a band")
     assert data["total"] == 1
     assert data["songs"][0]["filename"] == "a.archive"
+
+
+def test_unmatched_flag_and_quick_filter(server_mod, client):
+    # A per-card "no match" badge needs the row to carry the enrichment state.
+    _put(server_mod, filename="a.archive", title="Matched", artist="A")
+    _put(server_mod, filename="b.archive", title="Missed", artist="B")
+    server_mod.meta_db.apply_enrichment_match("b.archive", "h", "failed")   # no-match
+    rows = {s["filename"]: s for s in server_mod.meta_db.query_page()[0]}
+    assert rows["b.archive"]["unmatched"] is True
+    assert rows["a.archive"]["unmatched"] is False
+    # The "Unmatched" quick-filter (match=unmatched) returns only the failed song.
+    fns = [s["filename"] for s in client.get("/api/library?match=unmatched").json()["songs"]]
+    assert fns == ["b.archive"]

tests/test_mb_enrichment.py

@@ -97,6 +97,110 @@ def mb_doc(rid="rec-1", title="Thunderstruck", artist="AC/DC", artist_id="art-1"
     }
 
 
+# ── strict-then-loose search fallback ────────────────────────────────────────
+
+def test_search_falls_back_to_loose_when_strict_is_empty(server, monkeypatch):
+    """The strict field-phrase query misses a non-Latin-primary artist; the
+    loose retry (no field scoping) searches aliases and finds it."""
+    calls = []
+
+    def _routed(path, params):
+        q = params.get("query", "")
+        calls.append(q)
+        if q.startswith("recording:"):        # strict phrase → nothing
+            return {"recordings": []}
+        return {"recordings": [mb_doc(rid="rec-x", title="Telephone Number")]}
+
+    monkeypatch.setattr(server, "_mb_http_get", _routed)
+    cands = server._mb_search_recordings("Junko Ohashi", "Telephone Number")
+    assert len(cands) == 1
+    assert len(calls) == 2                     # strict first, then the loose retry
+    assert calls[0].startswith("recording:")   # strict is the field-phrase form
+    assert "artist:" not in calls[1] and '"' not in calls[1]   # loose retry
+
+
+def test_search_does_not_retry_when_strict_hits(server, monkeypatch):
+    """A strict hit must not spend a second (throttled) request on the loose
+    query."""
+    calls = []
+
+    def _routed(path, params):
+        calls.append(params.get("query", ""))
+        return {"recordings": [mb_doc()]}
+
+    monkeypatch.setattr(server, "_mb_http_get", _routed)
+    cands = server._mb_search_recordings("AC/DC", "Thunderstruck")
+    assert len(cands) == 1
+    assert len(calls) == 1
+
+
+# ── alias-aware scoring (non-Latin-primary artists) ──────────────────────────
+
+_AID = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+
+
+def test_artist_aliases_fetched_and_cached(server, monkeypatch):
+    calls = []
+
+    def fake(path, params):
+        calls.append(path)
+        return {"sort-name": "Ohashi, Junko",
+                "aliases": [{"name": "Junko Ohashi"}, {"name": "大橋 純子"}]}
+
+    monkeypatch.setattr(server, "_mb_http_get", fake)
+    names = server._mb_artist_aliases(_AID)
+    assert "Junko Ohashi" in names and "Ohashi, Junko" in names
+    server._mb_artist_aliases(_AID)          # cached → no second request
+    assert len(calls) == 1
+
+
+def test_artist_aliases_rejects_bad_id(server, monkeypatch):
+    def boom(path, params):
+        raise AssertionError("must not fetch for a non-UUID id")
+
+    monkeypatch.setattr(server, "_mb_http_get", boom)
+    assert server._mb_artist_aliases("not-a-uuid") == []
+
+
+def test_enrich_auto_matches_japanese_primary_via_alias(server, monkeypatch):
+    # A pack whose (romanized) artist MB stores under a Japanese primary name.
+    _put(server, "x.sloppak", title="Telephone Number", artist="Junko Ohashi")
+
+    def _routed(path, params):
+        if path.startswith("artist/"):                      # alias lookup
+            return {"sort-name": "Ohashi, Junko",
+                    "aliases": [{"name": "Junko Ohashi"}]}
+        q = params.get("query", "")
+        if q.startswith("recording:"):                      # strict phrase → nothing
+            return {"recordings": []}
+        return {"recordings": [mb_doc(rid="rec-jp", title="Telephone Number",
+                                      artist="大橋純子", artist_id=_AID)]}   # loose hit
+
+    monkeypatch.setattr(server, "_mb_http_get", _routed)
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("x.sloppak")
+    # The romanized alias lifts the artist over the auto floor → auto-confirmed.
+    assert row["match_state"] == "matched"
+    assert row["mb_recording_id"] == "rec-jp"
+
+
+# ── per-song field locks respected by the auto-matcher ───────────────────────
+
+def test_locked_field_not_canonicalized_by_auto_match(server, monkeypatch):
+    _put(server, "x.sloppak")                       # title "Thunderstruck (v2)", artist "ACDC"
+    server.meta_db.set_song_override("x.sloppak", "artist", locked=True)
+    monkeypatch.setattr(server, "_mb_http_get",
+                        lambda path, params: {"recordings": [mb_doc()]})
+    monkeypatch.setattr(server, "_enrich_network_enabled", lambda: True)
+    server._background_enrich()
+    row = server.meta_db.get_enrichment("x.sloppak")
+    assert row["match_state"] == "matched"          # still matches (identity applies)…
+    assert row["canon_artist"] is None              # …but the LOCKED artist isn't canonicalized
+    assert row["canon_title"] == "Thunderstruck"    # unlocked display fields still apply
+    assert row["mb_recording_id"]                   # identity keys still stored (art needs them)
+
+
 # ── offline safety (the pytest-never-hits-network contract) ──────────────────
 
 def test_offline_default_skips_matching(server, monkeypatch):

tests/test_mb_match.py

@@ -145,11 +145,40 @@ def test_rank_candidates_orders_by_our_score():
     assert all("score" in c for c in ranked)
 
 
+def test_rank_candidates_studio_preference_is_dropped_for_live_charts():
+    """Tied-score candidates: a studio chart prefers the studio take, but a
+    LIVE chart must NOT be forced to the studio recording."""
+    studio = {"recording_id": "studio", "artist": "AC/DC", "title": "Highway to Hell",
+              "studio": True, "mb_score": 90}
+    live = {"recording_id": "live", "artist": "AC/DC", "title": "Highway to Hell",
+            "studio": False, "mb_score": 95}
+    # Studio chart -> studio take wins the tie (studio flag), despite lower mb_score.
+    studio_song = {"artist": "AC/DC", "title": "Highway to Hell"}
+    assert m.rank_candidates(studio_song, [live, studio])[0]["recording_id"] == "studio"
+    # Live chart -> studio preference dropped, so the higher-mb_score live take wins.
+    live_song = {"artist": "AC/DC", "title": "Highway to Hell (Live at Donington)"}
+    assert m.rank_candidates(live_song, [studio, live])[0]["recording_id"] == "live"
+
+
 # ── query building ────────────────────────────────────────────────────────────
 
 def test_build_recording_query_denoises_and_quotes():
     q = m.build_recording_query("ACDC", 'Thunderstruck (v2)')
-    assert q == 'recording:"thunderstruck" AND artist:"acdc"'
+    # Live-only recordings are excluded — the studio take is never tagged Live,
+    # and it's the biggest source of junk in a flat recording search.
+    assert q == 'recording:"thunderstruck" AND artist:"acdc" AND -secondarytype:Live'
+
+
+def test_build_recording_query_keeps_live_for_live_charts():
+    """A chart that IS a live take must NOT get the live filter, or its only
+    correct recording is excluded. A bare title word ("Live and Let Die") is a
+    real word, not a marker, so it still filters."""
+    live = m.build_recording_query("AC/DC", "Highway to Hell (Live at Donington)")
+    assert "-secondarytype:Live" not in live
+    assert 'recording:"highway to hell"' in live
+    # A real word "live" in the title is not a live marker → still filtered.
+    bare = m.build_recording_query("Wings", "Live and Let Die")
+    assert "-secondarytype:Live" in bare
 
 
 def test_build_recording_query_escapes_and_handles_missing_artist():
@@ -160,6 +189,54 @@ def test_build_recording_query_escapes_and_handles_missing_artist():
     assert "artist:" not in q
 
 
+def test_build_recording_query_loose_drops_field_phrases():
+    # The strict form locks to the *primary* artist/title phrase (and drops
+    # live-only recordings — the chart isn't a live take).
+    assert m.build_recording_query("Junko Ohashi", "Telephone Number") == \
+        'recording:"telephone number" AND artist:"junko ohashi" AND -secondarytype:Live'
+    # The loose form has no field scoping and no phrases, so MusicBrainz also
+    # searches artist ALIASES — rescues non-Latin-primary artists (大橋純子) —
+    # but keeps the same live exclusion (a studio chart must not fall back to a
+    # live-only recording).
+    loose = m.build_recording_query("Junko Ohashi", "Telephone Number", loose=True)
+    assert loose == "(telephone number) AND (junko ohashi) AND -secondarytype:Live"
+    assert "artist:" not in loose and '"' not in loose
+
+
+def test_build_recording_query_loose_missing_artist():
+    assert m.build_recording_query("", "Fantasy", loose=True) == \
+        "(fantasy) AND -secondarytype:Live"
+
+
+def test_build_recording_query_loose_keeps_live_for_live_charts():
+    # A live chart's loose fallback must NOT exclude live recordings (same gate
+    # as the strict path) — else its only correct recording is filtered out.
+    loose = m.build_recording_query("AC/DC", "Highway to Hell (Live at Donington)", loose=True)
+    assert "-secondarytype:Live" not in loose
+    assert loose == "(highway to hell) AND (ac dc)"
+
+
+# ── alias-aware artist scoring ────────────────────────────────────────────────
+
+def test_cand_artist_sim_uses_aliases():
+    song = {"artist": "Junko Ohashi", "title": "Telephone Number"}
+    # primary is the Japanese name → romanized reference scores 0…
+    assert m.cand_artist_sim(song, {"artist": "大橋純子"}) == 0.0
+    # …but a romanized alias confirms it
+    assert m.cand_artist_sim(
+        song, {"artist": "大橋純子", "artist_aliases": ["Ohashi Junko", "Junko Ohashi"]}) == 1.0
+
+
+def test_alias_lifts_candidate_to_auto():
+    song = {"artist": "Junko Ohashi", "title": "Telephone Number"}
+    jp = {"artist": "大橋純子", "title": "Telephone Number"}
+    # Without the alias: title matches but the artist floor fails → never auto.
+    assert m.classify(song, jp, m.score_candidate(song, jp)) != "auto"
+    # With the romanized alias attached: artist clears the floor → auto.
+    jp_alias = dict(jp, artist_aliases=["Junko Ohashi"])
+    assert m.classify(song, jp_alias, m.score_candidate(song, jp_alias)) == "auto"
+
+
 # ── MusicBrainz response parsing ──────────────────────────────────────────────
 
 MB_DOC = {
@@ -200,6 +277,29 @@ def test_parse_recording_doc_normalizes():
     assert c["mb_score"] == 98
 
 
+def test_best_release_prefers_official_single_over_unofficial_album():
+    """An OFFICIAL single/EP must outrank an UNofficial bootleg album for the
+    canonical album/year: official comes before the studio-album preference, so
+    a single-only song is never seeded from a bootleg. (`(clean, status_ok, …)`
+    would wrongly pick the bootleg.)"""
+    doc = {
+        "id": "rec-x", "title": "One-Off", "score": 90,
+        "artist-credit": [
+            {"name": "A", "joinphrase": "",
+             "artist": {"id": "a", "name": "A", "sort-name": "A"}}],
+        "releases": [
+            {"id": "rel-boot", "title": "Boot LP", "status": "Bootleg",
+             "date": "1990-01-01", "release-group": {"primary-type": "Album"}},
+            {"id": "rel-single", "title": "The Single", "status": "Official",
+             "date": "1988-01-01", "release-group": {"primary-type": "Single"}},
+        ],
+    }
+    c = m.parse_recording_doc(doc)
+    assert c["release_id"] == "rel-single"
+    assert c["album"] == "The Single"
+    assert c["studio"] is False   # a Single isn't a clean studio ALBUM
+
+
 def test_parse_recording_doc_joined_artist_credit():
     doc = dict(MB_DOC)
     doc["artist-credit"] = [

tests/test_settings_api.py

@@ -753,29 +753,142 @@ def test_defaults_include_gameplay_keys(client, tmp_path):
     assert data["fail_behavior"] == "continue"
 
 
+
+def test_get_settings_exposes_default_instrument_profiles(client, tmp_path):
+    data = client.get("/api/settings").json()
+    assert data["active_instrument_profile"] == "guitar-lead"
+    assert set(data["instrument_profiles"]) == {"guitar-lead", "guitar-rhythm", "bass"}
+    assert data["instrument"] == "guitar"
+    assert data["string_count"] == 6
+    assert data["tuning"] == "Standard"
+    assert data["pathway"] == "songs"
+
+
+def test_post_flat_instrument_updates_active_profile(client, tmp_path):
+    r = client.post("/api/settings", json={"instrument": "bass", "pathway": "practice"})
+    assert r.status_code == 200
+    cfg = _read_cfg(tmp_path)
+    assert cfg["active_instrument_profile"] == "bass"
+    assert cfg["instrument"] == "bass"
+    assert cfg["string_count"] == 4
+    assert cfg["tuning"] == "Standard"
+    assert cfg["pathway"] == "practice"
+    assert cfg["instrument_profiles"]["bass"]["string_count"] == 4
+    assert cfg["instrument_profiles"]["bass"]["pathway"] == "practice"
+
+
+def test_post_instrument_profiles_mirrors_active_profile(client, tmp_path):
+    r = client.post("/api/settings", json={
+        "active_instrument_profile": "guitar-rhythm",
+        "instrument_profiles": {
+            "guitar-rhythm": {
+                "string_count": 7,
+                "tuning": "Drop A",
+                "reference_pitch": 432,
+                "pathway": "studio",
+            },
+            "bass": {
+                "string_count": 6,
+                "tuning": "C Standard",
+            },
+        },
+    })
+    assert r.status_code == 200
+    cfg = _read_cfg(tmp_path)
+    assert cfg["active_instrument_profile"] == "guitar-rhythm"
+    assert cfg["instrument"] == "guitar"
+    assert cfg["string_count"] == 7
+    assert cfg["tuning"] == "Drop A"
+    assert cfg["reference_pitch"] == 432
+    assert cfg["pathway"] == "studio"
+
+
+def test_post_pathway_rejects_bad_value(client, tmp_path):
+    (tmp_path / "config.json").write_text(json.dumps({"pathway": "songs"}))
+    r = client.post("/api/settings", json={"pathway": "invalid"})
+    assert "error" in r.json()
+    assert _read_cfg(tmp_path)["pathway"] == "songs"
+
+
+def test_post_instrument_profiles_rejects_bad_custom_string_count(client, tmp_path):
+    r = client.post("/api/settings", json={
+        "instrument_profiles": {
+            "bass": {"string_count": 6, "tuning": [0, 0, 0, 0]},
+        },
+    })
+    assert "error" in r.json()
+
 # ── /api/settings/reset ─────────────────────────────────────────────────────
 
 def test_reset_clears_requested_keys(client, tmp_path):
     (tmp_path / "config.json").write_text(json.dumps({
         "master_difficulty": 40,
         "countdown_before_song": True,
+        "pathway": "studio",
         "default_arrangement": "Lead",
         "demucs_server_url": "http://demucs.example:9000",
     }))
     r = client.post("/api/settings/reset",
-                    json={"keys": ["master_difficulty", "countdown_before_song"]})
+                    json={"keys": ["master_difficulty", "countdown_before_song", "pathway"]})
     assert r.status_code == 200
     body = r.json()
-    assert set(body["reset"]) == {"master_difficulty", "countdown_before_song"}
+    assert set(body["reset"]) == {"master_difficulty", "countdown_before_song", "pathway"}
     cfg = _read_cfg(tmp_path)
     # Reset removes the key so GET falls back to the default.
     assert "master_difficulty" not in cfg
     assert "countdown_before_song" not in cfg
+    assert "pathway" not in cfg
     # Unlisted keys are untouched.
     assert cfg["default_arrangement"] == "Lead"
     assert cfg["demucs_server_url"] == "http://demucs.example:9000"
 
 
+def test_partial_instrument_profiles_update_preserves_others(client, tmp_path):
+    # /api/settings is a partial-merge endpoint, so a POST that carries only ONE
+    # instrument profile must not reset the others to defaults.
+    gl = client.get("/api/settings").json()["instrument_profiles"]["guitar-lead"]
+    gl = dict(gl); gl["tuning"] = "Drop D"
+    client.post("/api/settings", json={"instrument_profiles": {"guitar-lead": gl}})
+    assert (client.get("/api/settings").json()["instrument_profiles"]
+            ["guitar-lead"]["tuning"] == "Drop D")
+    # Now update ONLY bass (Drop D is valid for a 4-string bass).
+    bass = client.get("/api/settings").json()["instrument_profiles"]["bass"]
+    bass = dict(bass); bass["tuning"] = "Drop D"
+    client.post("/api/settings", json={"instrument_profiles": {"bass": bass}})
+    out = client.get("/api/settings").json()["instrument_profiles"]
+    assert out["guitar-lead"]["tuning"] == "Drop D", "the untouched profile survived"
+    assert out["bass"]["tuning"] == "Drop D"
+
+
+def test_active_profile_switch_on_fresh_config(client, tmp_path):
+    # A fresh config has no instrument_profiles; an explicit active-profile
+    # switch must be honored, not overwritten by the profile inferred from the
+    # legacy flat defaults (guitar-lead).
+    r = client.post("/api/settings", json={"active_instrument_profile": "bass"})
+    assert r.status_code == 200 and "error" not in r.json()
+    got = client.get("/api/settings").json()
+    assert got["active_instrument_profile"] == "bass"
+    assert got["instrument"] == "bass"
+
+
+def test_reset_pathway_reaches_into_instrument_profiles(client, tmp_path):
+    # pathway is mirrored into every instrument profile, so a Gameplay reset
+    # that only deleted the flat key would leave GET re-deriving the old value
+    # from the profile. The reset must reach into the persisted profiles too.
+    client.post("/api/settings", json={"pathway": "studio"})
+    assert client.get("/api/settings").json()["pathway"] == "studio"
+    profiles = _read_cfg(tmp_path)["instrument_profiles"]
+    assert any(p["pathway"] == "studio" for p in profiles.values())
+
+    r = client.post("/api/settings/reset", json={"keys": ["pathway"]})
+    assert r.status_code == 200
+    assert "pathway" in r.json()["reset"]
+    # GET re-derives from the profile — which must now be back to the default.
+    assert client.get("/api/settings").json()["pathway"] == "songs"
+    for prof in _read_cfg(tmp_path)["instrument_profiles"].values():
+        assert prof["pathway"] == "songs"
+
+
 def test_reset_ignores_unknown_keys(client, tmp_path):
     (tmp_path / "config.json").write_text(json.dumps({"master_difficulty": 40}))
     # Unknown / non-resettable keys are silently ignored, not an error, and

tests/test_settings_instrument.py

@@ -31,12 +31,14 @@ def _cfg(tmp_path):
 def test_instrument_fields_persist(env):
     srv, tmp = env
     c = TestClient(srv.app)
+    # "Drop A" is the 5-string bass drop tuning (its low string is B, not E, so
+    # "Drop D" is a 4-string tuning — now correctly rejected per-profile).
     r = c.post("/api/settings", json={"instrument": "bass", "string_count": 5,
-                                      "tuning": "Drop D", "reference_pitch": 442})
+                                      "tuning": "Drop A", "reference_pitch": 442})
     assert r.status_code == 200
     cfg = _cfg(tmp)
     assert cfg["instrument"] == "bass" and cfg["string_count"] == 5
-    assert cfg["tuning"] == "Drop D" and cfg["reference_pitch"] == 442.0
+    assert cfg["tuning"] == "Drop A" and cfg["reference_pitch"] == 442.0
     # Reflected back through GET.
     got = c.get("/api/settings").json()
     assert got["instrument"] == "bass" and got["reference_pitch"] == 442.0

tests/test_tunings.py

@@ -2,7 +2,31 @@
 
 import pytest
 
-from tunings import tuning_name
+from tunings import (
+    DEFAULT_TUNINGS,
+    TUNING_PRESET_MIDIS,
+    _valid_tuning_for_key,
+    apply_flat_instrument_patch_to_profiles,
+    open_midis_to_freqs,
+    settings_with_instrument_profiles,
+    tuning_midis_from_offsets,
+    tuning_name,
+    tuning_offsets_from_midis,
+    tuning_preset_offsets,
+)
+
+
+def test_valid_tuning_for_key_builtin_and_provider_names():
+    # A built-in valid for the key is accepted; a built-in valid only for a
+    # DIFFERENT key (misapplied, e.g. "Drop D" on a 5-string bass) is rejected.
+    assert _valid_tuning_for_key("bass-5", "Drop A") == "Drop A"
+    assert _valid_tuning_for_key("bass-5", "Drop D") is None
+    assert _valid_tuning_for_key("guitar-6", "Standard") == "Standard"
+    # A name unknown to every built-in table is a provider/custom tuning (tuner
+    # plugin, /api/tunings) the pure layer can't resolve — accept it so settings
+    # round-trip rather than normalizing it away to Standard.
+    assert _valid_tuning_for_key("bass-5", "My Custom DADGAD") == "My Custom DADGAD"
+    assert _valid_tuning_for_key("guitar-6", "x" * 65) is None   # length cap kept
 
 
 # ── Standard tunings (all six strings share the same offset) ─────────────────
@@ -132,3 +156,96 @@ def test_drop_pattern_takes_precedence_over_named_dict():
     # auto-generator fires first and produces the same string. The named dict entry
     # is effectively dead code for this case — this test documents the behavior.
     assert tuning_name([-2, 0, 0, 0, 0, 0]) == "Drop D"
+
+
+# ── Host tuning profile catalogue -------------------------------------------
+
+def test_default_tunings_include_extended_host_profiles():
+    assert "bass-6" in DEFAULT_TUNINGS
+    assert "C Standard" in DEFAULT_TUNINGS["guitar-6"]
+    assert "C# Standard" in DEFAULT_TUNINGS["guitar-6"]
+    assert "Drop Ab" in DEFAULT_TUNINGS["guitar-6"]
+    assert "BEAD" in DEFAULT_TUNINGS["bass-4"]
+    assert "High C" in DEFAULT_TUNINGS["bass-5"]
+    assert "Drop A + Drop E" in DEFAULT_TUNINGS["guitar-8"]
+
+
+def test_default_tuning_frequencies_are_derived_from_midis():
+    assert DEFAULT_TUNINGS["guitar-6"]["Standard"] == open_midis_to_freqs([40, 45, 50, 55, 59, 64])
+    assert DEFAULT_TUNINGS["bass-6"]["Standard"] == open_midis_to_freqs([23, 28, 33, 38, 43, 48])
+
+
+def test_tuning_offsets_from_named_presets():
+    assert tuning_preset_offsets("guitar-6", "Drop D") == [-2, 0, 0, 0, 0, 0]
+    assert tuning_preset_offsets("guitar-6", "C Standard") == [-4, -4, -4, -4, -4, -4]
+    assert tuning_preset_offsets("bass-4", "BEAD") == [-5, -5, -5, -5]
+    assert tuning_preset_offsets("bass-5", "High C") == [5, 5, 5, 5, 5]
+
+
+def test_tuning_midis_round_trip_offsets():
+    offsets = [-2, 0, 0, 0, 0, 0]
+    midis = tuning_midis_from_offsets("guitar-6", offsets)
+    assert midis == TUNING_PRESET_MIDIS["guitar-6"]["Drop D"]
+    assert tuning_offsets_from_midis("guitar-6", midis) == offsets
+
+
+def test_tuning_conversion_rejects_wrong_string_count():
+    assert tuning_offsets_from_midis("guitar-6", [40, 45, 50, 55]) is None
+    assert tuning_midis_from_offsets("bass-4", [0, 0, 0, 0, 0]) is None
+
+def test_settings_profiles_default_to_lead_rhythm_and_bass():
+    settings = settings_with_instrument_profiles({})
+    assert settings["active_instrument_profile"] == "guitar-lead"
+    assert set(settings["instrument_profiles"]) == {"guitar-lead", "guitar-rhythm", "bass"}
+    assert settings["instrument"] == "guitar"
+    assert settings["string_count"] == 6
+    assert settings["tuning"] == "Standard"
+    assert settings["pathway"] == "songs"
+    assert settings["instrument_profiles"]["guitar-lead"]["pathway"] == "songs"
+
+
+def test_settings_profiles_migrate_legacy_flat_bass_selection():
+    settings = settings_with_instrument_profiles({
+        "instrument": "bass",
+        "string_count": 6,
+        "tuning": "C Standard",
+        "reference_pitch": 432,
+        "pathway": "practice",
+    })
+    assert settings["active_instrument_profile"] == "bass"
+    assert settings["instrument_profiles"]["bass"]["string_count"] == 6
+    assert settings["instrument_profiles"]["bass"]["tuning"] == "C Standard"
+    assert settings["reference_pitch"] == 432
+    assert settings["pathway"] == "practice"
+    assert settings["instrument_profiles"]["bass"]["pathway"] == "practice"
+
+
+def test_flat_patch_updates_active_profile_and_mirrors_legacy_keys():
+    settings = settings_with_instrument_profiles({})
+    patched = apply_flat_instrument_patch_to_profiles(settings, {"tuning": "Drop D"})
+    assert patched["tuning"] == "Drop D"
+    assert patched["instrument_profiles"]["guitar-lead"]["tuning"] == "Drop D"
+
+
+def test_flat_pathway_patch_updates_active_profile_and_mirrors_legacy_key():
+    settings = settings_with_instrument_profiles({})
+    patched = apply_flat_instrument_patch_to_profiles(settings, {"pathway": "studio"})
+    assert patched["pathway"] == "studio"
+    assert patched["instrument_profiles"]["guitar-lead"]["pathway"] == "studio"
+
+
+def test_flat_instrument_patch_defaults_to_target_string_count():
+    settings = settings_with_instrument_profiles({"instrument": "guitar", "string_count": 6, "tuning": "Drop D"})
+    patched = apply_flat_instrument_patch_to_profiles(settings, {"instrument": "bass"})
+    assert patched["instrument"] == "bass"
+    assert patched["string_count"] == 4
+    assert patched["tuning"] == "Standard"
+    assert patched["active_instrument_profile"] == "bass"
+    assert patched["instrument_profiles"]["bass"]["string_count"] == 4
+
+
+def test_flat_string_count_patch_resets_incompatible_named_tuning():
+    settings = settings_with_instrument_profiles({"instrument": "guitar", "string_count": 6, "tuning": "DADGAD"})
+    patched = apply_flat_instrument_patch_to_profiles(settings, {"string_count": 7})
+    assert patched["string_count"] == 7
+    assert patched["tuning"] == "Standard"