feat(web): crossfade between tracks (Tier C11)

Operator-tunable 0-12s crossfade in Settings → Playback. Default 0
(off). Most albums sound best at 0 — gapless masters, classical, and
live recordings all suffer noticeable crossfades.

Implementation: pure-function position-derived volume scalar.
`deriveFadeScalar(position, duration, crossfadeSec)` ramps from 0 to
1 over the leading X seconds, 1 to 0 over the trailing X seconds,
and stays at 1 in between. Tracks shorter than 2X don't fade.

The layout's audio-volume effect now multiplies player.volume by
the fade scalar — no timers, no AudioContext, no element swapping.
Re-renders at the ~4Hz `timeupdate` cadence give 16 discrete steps
over a 4s fade, audibly close to smooth. Smoothing to per-frame
ramps via rAF is a follow-up if needed.

Setting persists to localStorage as `minstrel.crossfade` (matches
the existing volume-storage convention).

Tests cover the pure derivation (off, too-short track, fade-in,
fade-out) + clamp/persist on setCrossfade + invalid-input recovery
on readStoredCrossfade.

web/src/lib/player/store.svelte.ts

@@ -10,6 +10,10 @@ export type PlayerState = 'idle' | 'loading' | 'playing' | 'paused' | 'error';
 export type RepeatMode = 'off' | 'all' | 'one';
 
 const VOLUME_KEY = 'minstrel.volume';
+const CROSSFADE_KEY = 'minstrel.crossfade';
+
+const CROSSFADE_MIN = 0;
+const CROSSFADE_MAX = 12;
 
 export function readStoredVolume(): number {
   const raw = storage.read(VOLUME_KEY);
@@ -19,12 +23,43 @@ export function readStoredVolume(): number {
   return 1;
 }
 
+export function readStoredCrossfade(): number {
+  const raw = storage.read(CROSSFADE_KEY);
+  if (raw == null) return 0;
+  const n = Number(raw);
+  if (Number.isFinite(n) && n >= CROSSFADE_MIN && n <= CROSSFADE_MAX) {
+    return Math.round(n);
+  }
+  return 0;
+}
+
+// Pure-function: maps (position, duration, crossfadeSec) → volume scalar
+// in [0,1]. Outside the crossfade windows it's 1. In the leading X
+// seconds: position/X (fade-in). In the trailing X seconds:
+// (duration-position)/X (fade-out). Tracks shorter than 2X don't fade.
+export function deriveFadeScalar(
+  position: number,
+  duration: number,
+  crossfadeSec: number
+): number {
+  if (crossfadeSec <= 0 || duration <= 0) return 1;
+  if (duration < crossfadeSec * 2) return 1;
+  if (position < crossfadeSec) {
+    return Math.max(0, Math.min(1, position / crossfadeSec));
+  }
+  if (duration - position < crossfadeSec) {
+    return Math.max(0, Math.min(1, (duration - position) / crossfadeSec));
+  }
+  return 1;
+}
+
 let _queue    = $state<TrackRef[]>([]);
 let _index    = $state(0);
 let _state    = $state<PlayerState>('idle');
 let _position = $state(0);
 let _duration = $state(0);
 let _volume   = $state(readStoredVolume());
+let _crossfadeSec = $state(readStoredCrossfade());
 let _shuffle  = $state(false);
 let _repeat   = $state<RepeatMode>('off');
 let _error    = $state<string | null>(null);
@@ -59,6 +94,7 @@ export const player = {
   get position()  { return _position; },
   get duration()  { return _duration; },
   get volume()    { return _volume; },
+  get crossfadeSec() { return _crossfadeSec; },
   get shuffle()   { return _shuffle; },
   get repeat()    { return _repeat; },
   get error()     { return _error; },
@@ -166,6 +202,12 @@ export function setVolume(v: number): void {
   storage.write(VOLUME_KEY, String(clamped));
 }
 
+export function setCrossfade(sec: number): void {
+  const clamped = Math.max(CROSSFADE_MIN, Math.min(CROSSFADE_MAX, Math.round(sec)));
+  _crossfadeSec = clamped;
+  storage.write(CROSSFADE_KEY, String(clamped));
+}
+
 // Last non-zero volume captured so the M shortcut can toggle to silent
 // then restore. Set lazily on the first toggle and on any setVolume
 // that's non-zero. Default 0.5 keeps unmute usable even if the user

web/src/lib/player/store.test.ts

@@ -591,3 +591,55 @@ describe('queue mutations', () => {
     expect(player.queue.map((x) => x.id)).toEqual(['a']);
   });
 });
+
+describe('crossfade', () => {
+  test('deriveFadeScalar returns 1 when crossfadeSec is 0', async () => {
+    const { deriveFadeScalar } = await import('./store.svelte');
+    expect(deriveFadeScalar(50, 200, 0)).toBe(1);
+    expect(deriveFadeScalar(0, 200, 0)).toBe(1);
+    expect(deriveFadeScalar(200, 200, 0)).toBe(1);
+  });
+
+  test('deriveFadeScalar returns 1 when track is too short to fade twice', async () => {
+    const { deriveFadeScalar } = await import('./store.svelte');
+    // 6s track with 4s crossfade: 6 < 4*2, so no fade.
+    expect(deriveFadeScalar(0, 6, 4)).toBe(1);
+    expect(deriveFadeScalar(3, 6, 4)).toBe(1);
+  });
+
+  test('deriveFadeScalar ramps in over the leading X seconds', async () => {
+    const { deriveFadeScalar } = await import('./store.svelte');
+    // 60s track, 4s crossfade.
+    expect(deriveFadeScalar(0, 60, 4)).toBe(0);
+    expect(deriveFadeScalar(2, 60, 4)).toBe(0.5);
+    expect(deriveFadeScalar(4, 60, 4)).toBe(1);
+  });
+
+  test('deriveFadeScalar ramps out over the trailing X seconds', async () => {
+    const { deriveFadeScalar } = await import('./store.svelte');
+    expect(deriveFadeScalar(56, 60, 4)).toBe(1);
+    expect(deriveFadeScalar(58, 60, 4)).toBe(0.5);
+    expect(deriveFadeScalar(60, 60, 4)).toBe(0);
+  });
+
+  test('setCrossfade clamps to [0, 12] and persists', async () => {
+    const { setCrossfade, player } = await import('./store.svelte');
+    setCrossfade(4);
+    expect(player.crossfadeSec).toBe(4);
+    expect(localStorage.getItem('minstrel.crossfade')).toBe('4');
+    setCrossfade(99);
+    expect(player.crossfadeSec).toBe(12);
+    setCrossfade(-3);
+    expect(player.crossfadeSec).toBe(0);
+  });
+
+  test('readStoredCrossfade survives an invalid stored value', async () => {
+    const { readStoredCrossfade } = await import('./store.svelte');
+    localStorage.setItem('minstrel.crossfade', 'banana');
+    expect(readStoredCrossfade()).toBe(0);
+    localStorage.setItem('minstrel.crossfade', '500');
+    expect(readStoredCrossfade()).toBe(0);
+    localStorage.setItem('minstrel.crossfade', '7');
+    expect(readStoredCrossfade()).toBe(7);
+  });
+});