From bc3db9e4f7a5a24d2ec7d41904e7ee676a04ffd0 Mon Sep 17 00:00:00 2001
From: Samu <me@samu.lol>
Date: Thu, 3 Sep 2026 20:37:38 +0200
Subject: [PATCH] docs: wave 1 implementation plan (15 tasks)

---
 docs/superpowers/plans/2026-09-03-wave1.md | 2582 ++++++++++++++++++++
 1 file changed, 2582 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-03-wave1.md

diff --git a/docs/superpowers/plans/2026-09-03-wave1.md b/docs/superpowers/plans/2026-09-03-wave1.md
new file mode 100644
index 0000000..55449a0
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-03-wave1.md
@@ -0,0 +1,2582 @@
+# Wave 1 Implementation Plan (plan 3)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship Wave 1: schema versioning + live migration, built-in album player with last-played tracking, loan tracking, rip queue, stats wall, and JSON export + SQLite backups.
+
+**Architecture:** Extends the existing Fastify/SQLite backend (server/) and React SPA (web/) without changing the frozen plan-1 API. New routes: stream/album proxy, loans, stats, export/backup. First schema migration via `app_meta.schema_version`. Player is a global context above the router so audio survives navigation.
+
+**Tech Stack:** unchanged (Fastify 5, better-sqlite3, React 19, Vite, Vitest). Spec: `docs/superpowers/specs/2026-09-03-wave1-hygiene-listening-design.md`.
+
+**Prerequisites:** main (post plan 2), 147/147 tests. Branch: `wave1-hygiene-listening`. Node >= 20.
+
+**Stamping refinement vs spec:** Subsonic's recent-list entries don't reliably carry a played timestamp. `last_played_at` is therefore stamped from two sources: (1) sync, when an album entry reports one (`played`/`playedAt` field, OpenSubsonic-style — opportunistic, null-safe), and (2) the built-in player, via `POST /api/album/:subsonicId/played` on playback start. UX is identical.
+
+---
+
+## File structure (plan 3)
+
+```
+server/src/
+├── db.ts                  # MODIFY: versioned migrate(), loans table, last_played_at
+├── config.ts              # MODIFY: backupsDir
+├── subsonic.ts            # MODIFY: getAlbum(), getRecentAlbums(), public url()
+├── sync.ts                # MODIFY: stamp last_played_at
+├── ripstatus.ts           # MODIFY: findMatchedAlbum()
+├── routes/
+│   ├── collectionRoutes.ts # MODIFY: detail gains matchedAlbum, onLoan filter
+│   ├── streamRoutes.ts     # NEW: /api/stream/:songId, /api/album/:id/tracks, /api/album/:id/played
+│   ├── loanRoutes.ts       # NEW: loans CRUD
+│   ├── statsRoutes.ts      # NEW: /api/stats
+│   └── dataRoutes.ts       # NEW: /api/export, /api/backup, /api/backups
+└── test/ (new: migrate.test.ts, loans.test.ts, stats.test.ts, data.test.ts, stream.test.ts; modified: subsonic.test.ts, sync.test.ts, collection.test.ts)
+web/src/
+├── types.ts               # MODIFY: Track, Stats, Loan, Backups, matchedAlbum
+├── api.ts                 # MODIFY: new methods
+├── player/PlayerContext.tsx # NEW: global player state + <audio>
+├── player/MiniBar.tsx     # NEW: mini-bar + expanded panel
+├── pages/ItemPage.tsx     # MODIFY: Play, last played, loan section
+├── pages/LibraryPage.tsx  # MODIFY: header links, On loan chip
+├── pages/QueuePage.tsx    # NEW
+├── pages/StatsPage.tsx    # NEW
+├── pages/SettingsPage.tsx # MODIFY: Data section
+├── App.tsx                # MODIFY: routes + PlayerProvider
+└── test/ (new: player.test.tsx, queue.test.tsx, stats.test.tsx; modified: item, library, settings, api tests)
+```
+
+---
+
+### Task 1: Schema versioning — migration v2
+
+**Files:**
+- Modify: `server/src/db.ts`, `server/src/config.ts`
+- Test: `server/test/migrate.test.ts`
+
+- [ ] **Step 1: Write the failing test `server/test/migrate.test.ts`**
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import Database from 'better-sqlite3'
+import { openDatabase } from '../src/db.js'
+
+/** Builds a pre-v2 database (plan-1 schema, no version row, no new columns). */
+function legacyDb(): Database.Database {
+  const db = new Database(':memory:')
+  db.pragma('journal_mode = WAL')
+  db.pragma('foreign_keys = ON')
+  db.exec(`
+    CREATE TABLE app_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+    CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT NOT NULL UNIQUE, password_hash TEXT NOT NULL, is_admin INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL DEFAULT (datetime('now')));
+    CREATE TABLE sessions (token TEXT PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE, created_at TEXT NOT NULL DEFAULT (datetime('now')), expires_at TEXT NOT NULL);
+    CREATE TABLE settings (user_id INTEGER PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE, discogs_token TEXT, subsonic_url TEXT, subsonic_username TEXT, subsonic_password TEXT);
+    CREATE TABLE collection_items (id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE, discogs_release_id INTEGER NOT NULL, title TEXT NOT NULL, artist TEXT NOT NULL, year INTEGER, formats TEXT NOT NULL DEFAULT '[]', genres TEXT NOT NULL DEFAULT '[]', labels TEXT NOT NULL DEFAULT '[]', tracklist TEXT NOT NULL DEFAULT '[]', catno TEXT, country TEXT, cover_url TEXT, local_artwork_path TEXT, barcodes TEXT NOT NULL DEFAULT '[]', rip_override INTEGER, date_added TEXT NOT NULL DEFAULT (datetime('now')), UNIQUE (user_id, discogs_release_id));
+    CREATE TABLE digital_albums (id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE, subsonic_id TEXT NOT NULL, title TEXT NOT NULL, artist TEXT NOT NULL, UNIQUE (user_id, subsonic_id));
+    CREATE TABLE match_links (user_id INTEGER NOT NULL, item_id INTEGER NOT NULL REFERENCES collection_items(id) ON DELETE CASCADE, album_id INTEGER NOT NULL REFERENCES digital_albums(id) ON DELETE CASCADE, PRIMARY KEY (user_id, item_id));
+    INSERT INTO users (id, username, password_hash, is_admin) VALUES (1, 'sam', 'x', 1);
+    INSERT INTO digital_albums (id, user_id, subsonic_id, title, artist) VALUES (1, 1, 'a1', 'Motion', 'The Cinematic Orchestra');
+  `)
+  return db
+}
+
+function columns(db: Database.Database, table: string): string[] {
+  return (db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]).map((c) => c.name)
+}
+
+describe('schema migration v2', () => {
+  it('migrates a legacy database: loans table, last_played_at, version row', () => {
+    const db = legacyDb()
+    // run the exported upgrade path against the legacy db
+    migrateUpgrades(db)
+    expect(columns(db, 'digital_albums')).toContain('last_played_at')
+    expect(columns(db, 'loans')).toEqual([
+      'id',
+      'user_id',
+      'item_id',
+      'borrower',
+      'lent_at',
+      'returned_at',
+    ])
+    const version = db.prepare("SELECT value FROM app_meta WHERE key = 'schema_version'").get()
+    expect(version).toEqual({ value: '2' })
+    // existing data survives
+    expect(db.prepare('SELECT title FROM digital_albums').get()).toEqual({ title: 'Motion' })
+  })
+
+  it('openDatabase creates a fresh v2 database directly', () => {
+    const db = openDatabase(':memory:')
+    expect(columns(db, 'digital_albums')).toContain('last_played_at')
+    expect(columns(db, 'loans')).toContain('borrower')
+    const version = db.prepare("SELECT value FROM app_meta WHERE key = 'schema_version'").get()
+    expect(version).toEqual({ value: '2' })
+  })
+
+  it('migrations are idempotent', () => {
+    const db = openDatabase(':memory:')
+    expect(() => migrateUpgrades(db)).not.toThrow()
+    expect(
+      (db.prepare("SELECT value FROM app_meta WHERE key = 'schema_version'").get() as { value: string }).value
+    ).toBe('2')
+  })
+
+  let migrateUpgrades: (db: Database.Database) => void
+  beforeEach(() => {
+    // bound below after import — keeps the legacy-db helper readable
+    ;({ migrateUpgrades } = require('../src/db.js'))
+  })
+})
+```
+
+Note: the project is ESM — replace the `require` trick with a normal top-level import: `import { openDatabase, migrateUpgrades } from '../src/db.js'` and drop the beforeEach binding. The helper name must match what db.ts exports.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run server/test/migrate.test.ts`
+Expected: FAIL — `migrateUpgrades` is not exported.
+
+- [ ] **Step 3: Implement — modify `server/src/db.ts`**
+
+The current `migrate(db)` execs one big schema string. Restructure: keep that string as `BASE_SCHEMA` (rename the exec target; content unchanged — v1 schema exactly), add the versioned upgrade path, and export `migrateUpgrades`:
+
+```ts
+function getSchemaVersion(db: DB): number {
+  const row = db.prepare("SELECT value FROM app_meta WHERE key = 'schema_version'").get() as
+    | { value: string }
+    | undefined
+  return row ? Number(row.value) : 0
+}
+
+function setSchemaVersion(db: DB, version: number): void {
+  db.prepare(
+    `INSERT INTO app_meta (key, value) VALUES ('schema_version', ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+  ).run(String(version))
+}
+
+/** Upgrade steps for databases created before schema versioning existed. */
+export function migrateUpgrades(db: DB): void {
+  const version = getSchemaVersion(db)
+  if (version < 2) {
+    db.exec(`
+      ALTER TABLE digital_albums ADD COLUMN last_played_at TEXT;
+      CREATE TABLE IF NOT EXISTS loans (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        item_id INTEGER NOT NULL REFERENCES collection_items(id) ON DELETE CASCADE,
+        borrower TEXT NOT NULL,
+        lent_at TEXT NOT NULL DEFAULT (datetime('now')),
+        returned_at TEXT
+      );
+    `)
+    setSchemaVersion(db, 2)
+  }
+}
+
+export function migrate(db: DB): void {
+  db.exec(BASE_SCHEMA)
+  migrateUpgrades(db)
+}
+```
+
+(`migrate` is called from `openDatabase` as before; `BASE_SCHEMA` is the existing DDL string, unchanged.)
+
+- [ ] **Step 4: Add `backupsDir` to `server/src/config.ts`** — extend `Config` with `backupsDir: string` and in `loadConfig`:
+
+```ts
+  const backupsDir = path.join(dataDir, 'backups')
+  mkdirSync(backupsDir, { recursive: true })
+```
+(return `backupsDir` in the object; add `backupsDir: ':memory:'`-style literal to `server/test/helpers.ts` testConfig and the inline config in `server/test/app.test.ts` — real temp dir like artworkDir: `mkdtempSync(path.join(tmpdir(), 'rs-bak-'))`.)
+
+- [ ] **Step 5: Run tests**
+
+Run: `npx vitest run server/test/migrate.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS (147 + 3 new = 150). Any test constructing a raw config literal needs `backupsDir` added — fix those (app.test.ts, helpers.ts).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A && git commit -m "feat: schema versioning with v2 migration (loans, last_played_at)"
+```
+
+---
+
+### Task 2: Subsonic client — getAlbum, getRecentAlbums, public url()
+
+**Files:**
+- Modify: `server/src/subsonic.ts`
+- Test: `server/test/subsonic.test.ts` (append)
+
+- [ ] **Step 1: Append failing tests to `server/test/subsonic.test.ts`**
+
+```ts
+  it('url() builds a raw endpoint URL with auth params', () => {
+    const c = new SubsonicClient({
+      url: 'http://navidrome.local',
+      username: 'sam',
+      password: 'pass',
+      fetchImpl: (async () => subsonicResponse({})) as typeof fetch,
+    })
+    const u = new URL(c.url('stream', { id: 'song-9' }))
+    expect(u.pathname).toBe('/rest/stream')
+    expect(u.searchParams.get('id')).toBe('song-9')
+    expect(u.searchParams.get('u')).toBe('sam')
+    expect(u.searchParams.get('f')).toBe('json')
+  })
+
+  it('getAlbum returns ordered tracks', async () => {
+    const c = new SubsonicClient({
+      url: 'http://x',
+      username: 'sam',
+      password: 'pass',
+      fetchImpl: (async () =>
+        subsonicResponse({
+          'subsonic-response': {
+            status: 'ok',
+            album: {
+              id: 'alb-1',
+              name: 'Motion',
+              artist: 'The Cinematic Orchestra',
+              song: [
+                { id: 's2', title: 'Theme de Yoyo', duration: 300, track: 2 },
+                { id: 's1', title: 'Overture', duration: 200, track: 1 },
+              ],
+            },
+          },
+        })) as typeof fetch,
+    })
+    const album = await c.getAlbum('alb-1')
+    expect(album).toEqual({
+      id: 'alb-1',
+      title: 'Motion',
+      artist: 'The Cinematic Orchestra',
+      tracks: [
+        { id: 's1', title: 'Overture', duration: 200, track: 1 },
+        { id: 's2', title: 'Theme de Yoyo', duration: 300, track: 2 },
+      ],
+    })
+  })
+
+  it('getRecentAlbums returns the recent list raw', async () => {
+    const c = new SubsonicClient({
+      url: 'http://x',
+      username: 'sam',
+      password: 'pass',
+      fetchImpl: (async () =>
+        subsonicResponse({
+          'subsonic-response': {
+            status: 'ok',
+            albumList2: {
+              album: [
+                { id: 'a1', name: 'Motion', artist: 'TCO', played: '2026-09-01T10:00:00Z' },
+                { id: 'a2', name: 'Blue Lines', artist: 'Massive Attack' },
+              ],
+            },
+          },
+        })) as typeof fetch,
+    })
+    const recent = await c.getRecentAlbums(500)
+    expect(recent).toEqual([
+      { id: 'a1', title: 'Motion', artist: 'TCO', playedAt: '2026-09-01T10:00:00Z' },
+      { id: 'a2', title: 'Blue Lines', artist: 'Massive Attack', playedAt: null },
+    ])
+  })
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run server/test/subsonic.test.ts`
+Expected: FAIL — url/getAlbum/getRecentAlbums not implemented.
+
+- [ ] **Step 3: Implement in `server/src/subsonic.ts`** — add to the class:
+
+```ts
+  /** Raw endpoint URL with auth params — for streaming passthrough. */
+  url(endpoint: string, params: Record<string, string> = {}): string {
+    const u = new URL(`${this.base}/rest/${endpoint}`)
+    const search = { ...this.authParams(), ...params }
+    for (const [k, v] of Object.entries(search)) u.searchParams.set(k, v)
+    return u.toString()
+  }
+
+  async getAlbum(albumId: string): Promise<{ id: string; title: string; artist: string; tracks: { id: string; title: string; duration: number | null; track: number | null }[] }> {
+    const envelope = await this.request('getAlbum', { id: albumId })
+    const album = envelope.album ?? {}
+    const songs: any[] = album.song ?? []
+    const tracks = songs
+      .map((s) => ({
+        id: String(s.id),
+        title: String(s.title ?? ''),
+        duration: Number.isFinite(Number(s.duration)) ? Number(s.duration) : null,
+        track: Number.isInteger(Number(s.track)) ? Number(s.track) : null,
+      }))
+      .sort((a, b) => (a.track ?? 9999) - (b.track ?? 9999))
+    return { id: String(album.id ?? albumId), title: album.name ?? album.title ?? '', artist: album.artist ?? '', tracks }
+  }
+
+  async getRecentAlbums(size = 500): Promise<{ id: string; title: string; artist: string; playedAt: string | null }[]> {
+    const envelope = await this.request('getAlbumList2', { type: 'recent', size: String(size) })
+    const list: any[] = envelope.albumList2?.album ?? []
+    return list.map((a) => ({
+      id: String(a.id),
+      title: a.name ?? a.title ?? '',
+      artist: a.artist ?? '',
+      playedAt: typeof a.played === 'string' ? a.played : typeof a.playedAt === 'string' ? a.playedAt : null,
+    }))
+  }
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `npx vitest run server/test/subsonic.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS (150 + 3 new = 153).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A && git commit -m "feat: subsonic getAlbum/getRecentAlbums and stream url builder"
+```
+
+---
+
+### Task 3: Sync stamps last_played_at + played endpoint
+
+**Files:**
+- Modify: `server/src/sync.ts`, `server/src/routes/streamRoutes.ts` (created in this task), `server/src/app.ts`
+- Test: `server/test/sync.test.ts` (new — move existing sync tests? No: library.test.ts holds sync tests; create `server/test/lastplayed.test.ts` instead)
+
+- [ ] **Step 1: Write the failing test `server/test/lastplayed.test.ts`**
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { buildTestApp, setupAdmin, auth } from './helpers.js'
+
+function stubWithRecent(recent: { id: number; name: string; artist: string; played?: string }[]): typeof fetch {
+  return (async (input: any) => {
+    const url = new URL(String(input))
+    if (url.pathname.endsWith('/rest/ping')) {
+      return new Response(JSON.stringify({ 'subsonic-response': { status: 'ok' } }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    }
+    if (url.pathname.endsWith('/rest/getAlbumList2')) {
+      const type = url.searchParams.get('type')
+      const body =
+        type === 'recent'
+          ? { 'subsonic-response': { status: 'ok', albumList2: { album: recent } } }
+          : { 'subsonic-response': { status: 'ok', albumList2: { album: [{ id: 1, name: 'Album 1', artist: 'Artist 0' }] } } }
+      return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } })
+    }
+    return new Response('nope', { status: 404 })
+  }) as typeof fetch
+}
+
+async function waitForDone(app: any, cookie: string, timeoutMs = 2000) {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    const state = (await app.inject({ method: 'GET', url: '/api/library/sync', ...auth(cookie) })).json()
+    if (state.status !== 'running') return state
+    await new Promise((r) => setTimeout(r, 10))
+  }
+  throw new Error('sync did not finish')
+}
+
+describe('last_played_at stamping', () => {
+  it('sync stamps played timestamps from the recent list', async () => {
+    const app = await buildTestApp(
+      stubWithRecent([{ id: 1, name: 'Album 1', artist: 'Artist 0', played: '2026-09-01T10:00:00Z' }])
+    )
+    const cookie = await setupAdmin(app)
+    await app.inject({
+      method: 'PUT',
+      url: '/api/settings',
+      ...auth(cookie),
+      payload: { subsonicUrl: 'http://n.local', subsonicUsername: 'sam', subsonicPassword: 'pass' },
+    })
+    await waitForDone(app, cookie)
+    const row = app.db
+      .prepare("SELECT last_played_at FROM digital_albums WHERE subsonic_id = '1'")
+      .get() as { last_played_at: string | null }
+    expect(row.last_played_at).toBe('2026-09-01T10:00:00Z')
+    await app.close()
+  })
+
+  it('played endpoint stamps now and returns 404 for unknown albums', async () => {
+    const app = await buildTestApp()
+    const cookie = await setupAdmin(app)
+    await app.inject({
+      method: 'POST',
+      url: '/api/library/albums/test-seed',
+      ...auth(cookie),
+      payload: { albums: [{ subsonicId: 'a1', title: 'Motion', artist: 'TCO' }] },
+    })
+    const before = (
+      app.db.prepare("SELECT last_played_at FROM digital_albums WHERE subsonic_id = 'a1'").get() as {
+        last_played_at: string | null
+      }
+    ).last_played_at
+    expect(before).toBeNull()
+
+    const res = await app.inject({ method: 'POST', url: '/api/album/a1/played', ...auth(cookie) })
+    expect(res.statusCode).toBe(200)
+    const after = (
+      app.db.prepare("SELECT last_played_at FROM digital_albums WHERE subsonic_id = 'a1'").get() as {
+        last_played_at: string | null
+      }
+    ).last_played_at
+    expect(after).toBeTruthy()
+
+    const missing = await app.inject({ method: 'POST', url: '/api/album/zzz/played', ...auth(cookie) })
+    expect(missing.statusCode).toBe(404)
+    await app.close()
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run server/test/lastplayed.test.ts`
+Expected: FAIL — played endpoint 404; sync doesn't stamp.
+
+- [ ] **Step 3: Modify `server/src/sync.ts` `run()`** — after the existing stale-deletion loop, inside the same transaction is not required (best-effort stamping):
+
+```ts
+      // best-effort: stamp played timestamps reported by the server
+      try {
+        const recent = await client.getRecentAlbums(500)
+        const stamp = this.db.prepare(
+          'UPDATE digital_albums SET last_played_at = ? WHERE user_id = ? AND subsonic_id = ?'
+        )
+        for (const r of recent) {
+          if (r.playedAt) stamp.run(r.playedAt, userId, r.id)
+        }
+      } catch {
+        // recency stamping is optional
+      }
+```
+
+- [ ] **Step 4: Create `server/src/routes/streamRoutes.ts`** — full file:
+
+```ts
+import { FastifyInstance } from 'fastify'
+import { SubsonicClient, SubsonicError } from '../subsonic.js'
+import { requireAuth } from './authRoutes.js'
+import { getSettings, subsonicConfigComplete } from './settingsRoutes.js'
+
+function clientFor(request: any): SubsonicClient | null {
+  const s = getSettings(request.server.db, request.user.id)
+  if (!subsonicConfigComplete(s)) return null
+  return new SubsonicClient({
+    url: s.subsonic_url as string,
+    username: s.subsonic_username as string,
+    password: s.subsonic_password as string,
+    fetchImpl: request.server.fetchImpl,
+  })
+}
+
+export async function registerStreamRoutes(app: FastifyInstance): Promise<void> {
+  app.get('/api/stream/:songId', { preHandler: [requireAuth] }, async (request, reply) => {
+    const client = clientFor(request)
+    if (!client) return reply.code(409).send({ error: 'no_subsonic_config' })
+    const songId = (request.params as { songId: string }).songId
+    const range = request.headers.range
+    let upstream: Response
+    try {
+      upstream = await request.server.fetchImpl(client.url('stream', { id: songId }), {
+        headers: range ? { Range: range } : {},
+      })
+    } catch {
+      return reply.code(502).send({ error: 'stream_unavailable' })
+    }
+    if (!upstream.ok && upstream.status !== 206) {
+      return reply.code(502).send({ error: 'stream_unavailable' })
+    }
+    const headers: Record<string, string> = {}
+    for (const h of ['content-type', 'content-length', 'content-range', 'accept-ranges']) {
+      const v = upstream.headers.get(h)
+      if (v) headers[h] = v
+    }
+    if (!upstream.headers.get('accept-ranges')) headers['accept-ranges'] = 'bytes'
+    return reply.code(upstream.status).headers(headers).send(upstream.body)
+  })
+
+  app.get('/api/album/:subsonicId/tracks', { preHandler: [requireAuth] }, async (request, reply) => {
+    const client = clientFor(request)
+    if (!client) return reply.code(409).send({ error: 'no_subsonic_config' })
+    try {
+      const album = await client.getAlbum((request.params as { subsonicId: string }).subsonicId)
+      return album
+    } catch (err) {
+      if (err instanceof SubsonicError) return reply.code(502).send({ error: 'subsonic_error', detail: err.message })
+      return reply.code(502).send({ error: 'subsonic_unreachable' })
+    }
+  })
+
+  app.post('/api/album/:subsonicId/played', { preHandler: [requireAuth] }, async (request, reply) => {
+    const subsonicId = (request.params as { subsonicId: string }).subsonicId
+    const info = request.server.db
+      .prepare(
+        'UPDATE digital_albums SET last_played_at = ? WHERE user_id = ? AND subsonic_id = ?'
+      )
+      .run(new Date().toISOString(), request.user.id, subsonicId)
+    if (info.changes === 0) return reply.code(404).send({ error: 'not_found' })
+    return { ok: true }
+  })
+}
+```
+
+- [ ] **Step 5: Register in `server/src/app.ts`** — import + `await registerStreamRoutes(app)` after `registerLibraryRoutes(app)`.
+
+- [ ] **Step 6: Run tests**
+
+Run: `npx vitest run server/test/lastplayed.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS (153 + 2 new = 155).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add -A && git commit -m "feat: last-played stamping via sync and played endpoint, stream/album proxy routes"
+```
+
+---
+
+### Task 4: Item detail gains matchedAlbum; list gains onLoan filter
+
+**Files:**
+- Modify: `server/src/ripstatus.ts`, `server/src/routes/collectionRoutes.ts`
+- Test: `server/test/ripstatus.test.ts` (append), `server/test/collection.test.ts` (append)
+
+- [ ] **Step 1: Append failing test to `server/test/ripstatus.test.ts`** (the file has a `db` fixture with users/items helpers — reuse `addAlbum`):
+
+```ts
+import { findMatchedAlbum } from '../src/ripstatus.js'
+
+describe('findMatchedAlbum', () => {
+  it('returns the match-linked album', () => {
+    addAlbum(1, 'Motion (Remastered)', 'The Cinematic Orchestra')
+    db.prepare('INSERT INTO match_links (user_id, item_id, album_id) VALUES (1, 10, 1)').run()
+    const m = findMatchedAlbum(db, 1, 10)
+    expect(m).toMatchObject({ subsonicId: 'sub-1', lastPlayedAt: null })
+  })
+
+  it('falls back to the confident fuzzy match', () => {
+    addAlbum(2, 'Motion!', 'Cinematic Orchestra')
+    const m = findMatchedAlbum(db, 1, 10)
+    expect(m).toMatchObject({ subsonicId: 'sub-2' })
+  })
+
+  it('returns null when nothing matches or the item is missing', () => {
+    expect(findMatchedAlbum(db, 1, 10)).toBeNull()
+    expect(findMatchedAlbum(db, 1, 9999)).toBeNull()
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run server/test/ripstatus.test.ts`
+Expected: FAIL — findMatchedAlbum not exported.
+
+- [ ] **Step 3: Implement `findMatchedAlbum` in `server/src/ripstatus.ts`** (after `resolveRipStatus`):
+
+```ts
+export interface MatchedAlbum {
+  id: number
+  subsonicId: string
+  lastPlayedAt: string | null
+}
+
+/** Album behind an item's rip match — link wins, else confident fuzzy match. Independent of rip_override. */
+export function findMatchedAlbum(db: DB, userId: number, itemId: number): MatchedAlbum | null {
+  const item = db
+    .prepare('SELECT id, title, artist FROM collection_items WHERE id = ? AND user_id = ?')
+    .get(itemId, userId) as { id: number; title: string; artist: string } | undefined
+  if (!item) return null
+
+  const link = db
+    .prepare(
+      `SELECT da.id, da.subsonic_id, da.last_played_at FROM match_links ml
+       JOIN digital_albums da ON da.id = ml.album_id WHERE ml.item_id = ?`
+    )
+    .get(itemId) as { id: number; subsonic_id: string; last_played_at: string | null } | undefined
+  if (link) {
+    return { id: link.id, subsonicId: link.subsonic_id, lastPlayedAt: link.last_played_at }
+  }
+
+  const album = db
+    .prepare(
+      `SELECT id, subsonic_id, last_played_at FROM digital_albums WHERE user_id = ?`
+    )
+    .all(userId) as { id: number; subsonic_id: string; last_played_at: string | null; title: string; artist: string }[]
+  const match = album.find((a) => isConfidentMatch(item, a))
+  return match
+    ? { id: match.id, subsonicId: match.subsonic_id, lastPlayedAt: match.last_played_at }
+    : null
+}
+```
+
+- [ ] **Step 4: Append failing tests to `server/test/collection.test.ts`** (reuse the file's `appWithToken`, `discogsStub`, `auth` helpers; use the test-seed route for albums):
+
+```ts
+  it('detail includes matchedAlbum (null when unmatched)', async () => {
+    const { app, cookie } = await appWithToken()
+    const added = await app.inject({ method: 'POST', url: '/api/collection', ...auth(cookie), payload: { releaseId: 1001 } })
+    const id = added.json().id as number
+    const detail = await app.inject({ method: 'GET', url: `/api/collection/${id}`, ...auth(cookie) })
+    expect(detail.json().matchedAlbum).toBeNull()
+
+    await app.inject({
+      method: 'POST',
+      url: '/api/library/albums/test-seed',
+      ...auth(cookie),
+      payload: { albums: [{ subsonicId: 'alb-9', title: 'Motion', artist: 'The Cinematic Orchestra' }] },
+    })
+    const again = await app.inject({ method: 'GET', url: `/api/collection/${id}`, ...auth(cookie) })
+    expect(again.json().matchedAlbum).toMatchObject({ subsonicId: 'alb-9', lastPlayedAt: null })
+    await app.close()
+  })
+
+  it('list supports onLoan=true filter', async () => {
+    const { app, cookie } = await appWithToken()
+    const added = await app.inject({ method: 'POST', url: '/api/collection', ...auth(cookie), payload: { releaseId: 1001 } })
+    const id = added.json().id as number
+    await app.inject({ method: 'POST', url: `/api/collection/${id}/loan`, ...auth(cookie), payload: { borrower: 'Bob' } })
+
+    const all = await app.inject({ method: 'GET', url: '/api/collection', ...auth(cookie) })
+    expect(all.json().items).toHaveLength(1)
+    const onLoan = await app.inject({ method: 'GET', url: '/api/collection?onLoan=true', ...auth(cookie) })
+    expect(onLoan.json().items).toHaveLength(1)
+    const notOnLoan = await app.inject({ method: 'GET', url: '/api/collection?onLoan=false', ...auth(cookie) })
+    expect(notOnLoan.json().items).toHaveLength(0)
+    await app.close()
+  })
+```
+
+(Note: the onLoan test depends on Task 5's loan route — it is a known-red handoff inside this task; Task 5 turns it green. Verify everything else passes here.)
+
+- [ ] **Step 5: Implement** — in `server/src/routes/collectionRoutes.ts`:
+
+Detail route: after `rowToItem`, attach matchedAlbum:
+```ts
+import { resolveRipStatus, findMatchedAlbum } from '../ripstatus.js'
+```
+```ts
+    const row = getItem(db, request.user.id, Number((request.params as { id: string }).id))
+    if (!row) return reply.code(404).send({ error: 'not_found' })
+    return { ...rowToItem(db, row), matchedAlbum: findMatchedAlbum(db, request.user.id, row.id) }
+```
+
+List route: extend the query destructure with `onLoan` and filter before returning (after the `q` filter):
+```ts
+    if (onLoan === 'true' || onLoan === 'false') {
+      const want = onLoan === 'true'
+      filtered = filtered.filter((i) => {
+        const has = !!db
+          .prepare('SELECT id FROM loans WHERE item_id = ? AND returned_at IS NULL')
+          .get(i.id)
+        return has === want
+      })
+    }
+```
+and the query type gains `onLoan?: string`.
+
+- [ ] **Step 6: Run tests**
+
+Run: `npx vitest run server/test/ripstatus.test.ts server/test/collection.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS except the onLoan handoff test (160 total = 155 + 5 new; 1 known-red).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add -A && git commit -m "feat: matchedAlbum on item detail, onLoan collection filter"
+```
+
+---
+
+### Task 5: Loan routes
+
+**Files:**
+- Create: `server/src/routes/loanRoutes.ts`
+- Test: `server/test/loans.test.ts`
+- Modify: `server/src/app.ts`
+
+- [ ] **Step 1: Write the failing test `server/test/loans.test.ts`**
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { buildTestApp, setupAdmin, auth } from './helpers.js'
+import { discogsReleaseFixture } from './fixtures.js'
+
+const discogsStub = (async (input: any) =>
+  String(input).includes('/releases/1001')
+    ? new Response(JSON.stringify(discogsReleaseFixture), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    : new Response('nope', { status: 404 })) as typeof fetch
+
+async function appWithItem() {
+  const app = await buildTestApp(discogsStub)
+  const cookie = await setupAdmin(app)
+  await app.inject({ method: 'PUT', url: '/api/settings', ...auth(cookie), payload: { discogsToken: 't' } })
+  const added = await app.inject({ method: 'POST', url: '/api/collection', ...auth(cookie), payload: { releaseId: 1001 } })
+  return { app, cookie, itemId: added.json().id as number }
+}
+
+describe('loans', () => {
+  it('lend, list active, return', async () => {
+    const { app, cookie, itemId } = await appWithItem()
+
+    const lend = await app.inject({
+      method: 'POST',
+      url: `/api/collection/${itemId}/loan`,
+      ...auth(cookie),
+      payload: { borrower: 'Bob' },
+    })
+    expect(lend.statusCode).toBe(200)
+    const loan = lend.json()
+    expect(loan).toMatchObject({ itemId, borrower: 'Bob', returnedAt: null })
+
+    const dup = await app.inject({
+      method: 'POST',
+      url: `/api/collection/${itemId}/loan`,
+      ...auth(cookie),
+      payload: { borrower: 'Eve' },
+    })
+    expect(dup.statusCode).toBe(409)
+    expect(dup.json()).toEqual({ error: 'already_on_loan' })
+
+    const list = await app.inject({ method: 'GET', url: '/api/loans', ...auth(cookie) })
+    expect(list.json().active).toHaveLength(1)
+    expect(list.json().history).toHaveLength(0)
+
+    const ret = await app.inject({ method: 'POST', url: `/api/loans/${loan.id}/return`, ...auth(cookie) })
+    expect(ret.statusCode).toBe(200)
+    const after = await app.inject({ method: 'GET', url: '/api/loans', ...auth(cookie) })
+    expect(after.json().active).toHaveLength(0)
+    expect(after.json().history).toHaveLength(1)
+
+    const again = await app.inject({ method: 'POST', url: `/api/loans/${loan.id}/return`, ...auth(cookie) })
+    expect(again.statusCode).toBe(404)
+    await app.close()
+  })
+
+  it('validates borrower and ownership', async () => {
+    const { app, cookie, itemId } = await appWithItem()
+    const empty = await app.inject({
+      method: 'POST',
+      url: `/api/collection/${itemId}/loan`,
+      ...auth(cookie),
+      payload: { borrower: '  ' },
+    })
+    expect(empty.statusCode).toBe(400)
+
+    const missing = await app.inject({
+      method: 'POST',
+      url: `/api/collection/9999/loan`,
+      ...auth(cookie),
+      payload: { borrower: 'Bob' },
+    })
+    expect(missing.statusCode).toBe(404)
+    await app.close()
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run server/test/loans.test.ts`
+Expected: FAIL — 404s on loan routes.
+
+- [ ] **Step 3: Create `server/src/routes/loanRoutes.ts`** — full file:
+
+```ts
+import { FastifyInstance } from 'fastify'
+import { requireAuth } from './authRoutes.js'
+
+interface LoanRow {
+  id: number
+  user_id: number
+  item_id: number
+  borrower: string
+  lent_at: string
+  returned_at: string | null
+}
+
+function toLoan(l: LoanRow) {
+  return { id: l.id, itemId: l.item_id, borrower: l.borrower, lentAt: l.lent_at, returnedAt: l.returned_at }
+}
+
+export async function registerLoanRoutes(app: FastifyInstance): Promise<void> {
+  app.post('/api/collection/:id/loan', { preHandler: [requireAuth] }, async (request, reply) => {
+    const db = request.server.db
+    const userId = request.user.id
+    const id = Number((request.params as { id: string }).id)
+    const item = db
+      .prepare('SELECT id FROM collection_items WHERE id = ? AND user_id = ?')
+      .get(id, userId)
+    if (!item) return reply.code(404).send({ error: 'not_found' })
+    const { borrower } = (request.body ?? {}) as { borrower?: string }
+    if (typeof borrower !== 'string' || borrower.trim() === '') {
+      return reply.code(400).send({ error: 'invalid_input', detail: 'borrower is required' })
+    }
+    const active = db
+      .prepare('SELECT id FROM loans WHERE item_id = ? AND returned_at IS NULL')
+      .get(id)
+    if (active) return reply.code(409).send({ error: 'already_on_loan' })
+    const info = db
+      .prepare('INSERT INTO loans (user_id, item_id, borrower) VALUES (?, ?, ?)')
+      .run(userId, id, borrower.trim())
+    const loan = db.prepare('SELECT * FROM loans WHERE id = ?').get(info.lastInsertRowid) as LoanRow
+    return reply.code(200).send(toLoan(loan))
+  })
+
+  app.get('/api/loans', { preHandler: [requireAuth] }, async (request) => {
+    const db = request.server.db
+    const userId = request.user.id
+    const active = db
+      .prepare('SELECT * FROM loans WHERE user_id = ? AND returned_at IS NULL ORDER BY lent_at DESC')
+      .all(userId) as LoanRow[]
+    const history = db
+      .prepare(
+        'SELECT * FROM loans WHERE user_id = ? AND returned_at IS NOT NULL ORDER BY returned_at DESC LIMIT 50'
+      )
+      .all(userId) as LoanRow[]
+    return { active: active.map(toLoan), history: history.map(toLoan) }
+  })
+
+  app.post('/api/loans/:id/return', { preHandler: [requireAuth] }, async (request, reply) => {
+    const db = request.server.db
+    const id = Number((request.params as { id: string }).id)
+    const info = db
+      .prepare("UPDATE loans SET returned_at = datetime('now') WHERE id = ? AND user_id = ? AND returned_at IS NULL")
+      .run(id, request.user.id)
+    if (info.changes === 0) return reply.code(404).send({ error: 'not_found' })
+    return { ok: true }
+  })
+}
+```
+
+- [ ] **Step 4: Register in `server/src/app.ts`** — import + `await registerLoanRoutes(app)` after `registerStreamRoutes(app)`.
+
+- [ ] **Step 5: Run tests**
+
+Run: `npx vitest run server/test/loans.test.ts server/test/collection.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS (160 + 2 new = 162; the Task 4 onLoan handoff test now green).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A && git commit -m "feat: loan tracking routes"
+```
+
+---
+
+### Task 6: Stats route
+
+**Files:**
+- Create: `server/src/routes/statsRoutes.ts`
+- Test: `server/test/stats.test.ts`
+- Modify: `server/src/app.ts`
+
+- [ ] **Step 1: Write the failing test `server/test/stats.test.ts`**
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { openDatabase } from '../src/db.js'
+import { buildTestAppWithDb, setupAdmin, auth } from './helpers.js'
+
+function seedItems(db: ReturnType<typeof openDatabase>) {
+  const ins = db.prepare(
+    `INSERT INTO collection_items (user_id, discogs_release_id, title, artist, year, formats, genres, date_added, rip_override)
+     VALUES (1, ?, ?, ?, ?, ?, ?, ?, ?)`
+  )
+  ins.run(1, 'Motion', 'The Cinematic Orchestra', 1999, JSON.stringify(['CD']), JSON.stringify(['Electronic']), '2026-08-01 10:00:00', null)
+  ins.run(2, 'Blue Lines', 'Massive Attack', 1991, JSON.stringify(['Vinyl']), JSON.stringify(['Electronic']), '2026-08-15 10:00:00', 1)
+  ins.run(3, 'Mezzanine', 'Massive Attack', 1998, JSON.stringify(['CD']), JSON.stringify(['Downtempo', 'Electronic']), '2026-08-20 10:00:00', null)
+  ins.run(4, 'Dummy', 'Portishead', 1994, JSON.stringify(['CD', 'Album']), JSON.stringify(['Downtempo']), '2025-09-01 10:00:00', null)
+  db.prepare("INSERT INTO loans (user_id, item_id, borrower) VALUES (1, 2, 'Bob')").run()
+}
+
+describe('GET /api/stats', () => {
+  it('aggregates totals, formats, genres, artists, months, ratio, loans', async () => {
+    const db = openDatabase(':memory:')
+    seedItems(db)
+    const app = await buildTestAppWithDb(db)
+    const cookie = await setupAdmin(app)
+    const res = await app.inject({ method: 'GET', url: '/api/stats', ...auth(cookie) })
+    expect(res.statusCode).toBe(200)
+    const s = res.json()
+    expect(s.totals).toEqual({ items: 4, ripped: 2, notRipped: 2, onLoan: 1 })
+    expect(s.ripRatio).toBeCloseTo(0.5)
+    expect(s.formats).toEqual([
+      { name: 'CD', count: 3 },
+      { name: 'Vinyl', count: 1 },
+      { name: 'Album', count: 1 },
+    ])
+    expect(s.topGenres.slice(0, 2)).toEqual([
+      { name: 'Electronic', count: 3 },
+      { name: 'Downtempo', count: 2 },
+    ])
+    expect(s.topArtists.slice(0, 2)).toEqual([
+      { name: 'Massive Attack', count: 2 },
+      { name: 'Portishead', count: 1 },
+    ])
+    const aug = s.addedByMonth.find((m: { month: string }) => m.month === '2026-08')
+    expect(aug).toEqual({ month: '2026-08', count: 3 })
+    await app.close()
+  })
+})
+```
+
+Note: rip counts in this fixture come from rip_override (Blue Lines override 1 = ripped; others auto → no digital albums → not_ripped). `Motion` and `Mezzanine` and `Dummy` are not_ripped → totals {4, 2 ripped? no...}. Recount: overrides — item 2 override 1 → ripped; items 1,3,4 override null + no albums → not_ripped. So ripped=1, notRipped=3, ratio 0.25. FIX the expected values: totals {items:4, ripped:1, notRipped:3, onLoan:1}, ripRatio 0.25, and `topArtists` Massive Attack 2 first. Use these corrected expectations in the final test.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run server/test/stats.test.ts`
+Expected: FAIL — 404.
+
+- [ ] **Step 3: Create `server/src/routes/statsRoutes.ts`** — full file:
+
+```ts
+import { FastifyInstance } from 'fastify'
+import { requireAuth } from './authRoutes.js'
+
+function countBy(values: string[]): { name: string; count: number }[] {
+  const map = new Map<string, number>()
+  for (const v of values) {
+    if (!v) continue
+    map.set(v, (map.get(v) ?? 0) + 1)
+  }
+  return [...map.entries()].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count)
+}
+
+export async function registerStatsRoutes(app: FastifyInstance): Promise<void> {
+  app.get('/api/stats', { preHandler: [requireAuth] }, async (request) => {
+    const db = request.server.db
+    const userId = request.user.id
+    const items = db
+      .prepare('SELECT id, title, artist, year, formats, genres, date_added, rip_override FROM collection_items WHERE user_id = ?')
+      .all(userId) as {
+      id: number
+      title: string
+      artist: string
+      year: number | null
+      formats: string
+      genres: string
+      date_added: string
+      rip_override: number | null
+    }[]
+
+    const rippedCounts = { ripped: 0, notRipped: 0 }
+    const formats: string[] = []
+    const genres: string[] = []
+    const months = new Map<string, number>()
+    for (const item of items) {
+      let ripped: boolean
+      if (item.rip_override !== null && item.rip_override !== undefined) {
+        ripped = item.rip_override === 1
+      } else {
+        ripped = !!db.prepare('SELECT album_id FROM match_links WHERE item_id = ?').get(item.id) ||
+          !!db
+            .prepare('SELECT id FROM digital_albums WHERE user_id = ?')
+            .all(userId)
+            .some((a: any) => a.title === item.title && a.artist === item.artist)
+      }
+      ripped ? rippedCounts.ripped++ : rippedCounts.notRipped++
+      for (const f of JSON.parse(item.formats) as string[]) formats.push(f)
+      for (const g of JSON.parse(item.genres) as string[]) genres.push(g)
+      const month = (item.date_added ?? '').slice(0, 7)
+      if (/^\d{4}-\d{2}$/.test(month)) months.set(month, (months.get(month) ?? 0) + 1)
+    }
+
+    const onLoan = (
+      db.prepare('SELECT COUNT(*) AS n FROM loans WHERE user_id = ? AND returned_at IS NULL').get(userId) as { n: number }
+    ).n
+
+    const addedByMonth: { month: string; count: number }[] = []
+    const now = new Date()
+    for (let i = 11; i >= 0; i--) {
+      const d = new Date(now.getFullYear(), now.getMonth() - i, 1)
+      const key = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`
+      addedByMonth.push({ month: key, count: months.get(key) ?? 0 })
+    }
+
+    const artists = countBy(items.map((i) => i.artist)).slice(0, 10)
+    const decades = countBy(items.map((i) => (i.year ? `${Math.floor(i.year / 10) * 10}s` : '')))
+
+    return {
+      totals: {
+        items: items.length,
+        ripped: rippedCounts.ripped,
+        notRipped: rippedCounts.notRipped,
+        onLoan,
+      },
+      ripRatio: items.length === 0 ? 0 : rippedCounts.ripped / items.length,
+      formats: countBy(formats),
+      decades,
+      topGenres: countBy(genres).slice(0, 10),
+      topArtists: artists,
+      addedByMonth,
+    }
+  })
+}
+```
+
+IMPORTANT consistency decision: the rip determination here reimplements resolution loosely (title/artist equality, no normalize). REUSE the real logic instead: import `resolveRipStatusBatch` from '../ripstatus.js' (plan-2 fix) and compute statuses for all items in one call:
+
+```ts
+    const statuses = resolveRipStatusBatch(db, userId, items)
+    items.forEach((item, i) => { ripped = statuses[i] === 'ripped' })
+```
+Implement with the batch call (zip items+statuses); drop the inline fuzzy check. The test expectations stand as corrected above.
+
+- [ ] **Step 4: Register in `server/src/app.ts`** — import + `await registerStatsRoutes(app)` after `registerLoanRoutes(app)`.
+
+- [ ] **Step 5: Run tests**
+
+Run: `npx vitest run server/test/stats.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS (162 + 1 new = 163).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A && git commit -m "feat: collection stats route"
+```
+
+---
+
+### Task 7: Export + backup routes
+
+**Files:**
+- Create: `server/src/routes/dataRoutes.ts`
+- Test: `server/test/data.test.ts`
+- Modify: `server/src/app.ts`
+
+- [ ] **Step 1: Write the failing test `server/test/data.test.ts`**
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { readdirSync } from 'node:fs'
+import path from 'node:path'
+import { buildTestApp, setupAdmin, loginAs, auth } from './helpers.js'
+
+async function appWithData() {
+  const app = await buildTestApp()
+  const cookie = await setupAdmin(app)
+  await app.inject({
+    method: 'POST',
+    url: '/api/library/albums/test-seed',
+    ...auth(cookie),
+    payload: { albums: [{ subsonicId: 'a1', title: 'Motion', artist: 'TCO' }] },
+  })
+  await app.inject({
+    method: 'POST',
+    url: '/api/collection/1/loan',
+    ...auth(cookie),
+    payload: { borrower: 'Bob' },
+  }).catch(() => {})
+  return { app, cookie }
+}
+
+describe('export', () => {
+  it('returns per-user data without secrets', async () => {
+    const { app, cookie } = await appWithData()
+    await app.inject({ method: 'PUT', url: '/api/settings', ...auth(cookie), payload: { discogsToken: 'secret-token' } })
+    const res = await app.inject({ method: 'GET', url: '/api/export', ...auth(cookie) })
+    expect(res.statusCode).toBe(200)
+    const body = res.json()
+    expect(body.exportedAt).toBeTruthy()
+    expect(body.items).toEqual([])
+    expect(body.loans).toEqual([])
+    expect(body.matchLinks).toEqual([])
+    expect(JSON.stringify(body)).not.toContain('secret-token')
+    await app.close()
+  })
+})
+
+describe('backups', () => {
+  it('non-admin cannot trigger backups', async () => {
+    const app = await buildTestApp()
+    const cookie = await setupAdmin(app)
+    const bob = await loginAs(app, cookie, 'bob', 'bobpass123')
+    const res = await app.inject({ method: 'POST', url: '/api/backup', ...auth(bob) })
+    expect(res.statusCode).toBe(403)
+    await app.close()
+  })
+
+  it('admin creates a backup file and lists it', async () => {
+    const app = await buildTestApp()
+    const cookie = await setupAdmin(app)
+    const res = await app.inject({ method: 'POST', url: '/api/backup', ...auth(cookie) })
+    expect(res.statusCode).toBe(200)
+    expect(res.json().file).toMatch(/record-shop-.*\.db$/)
+    const list = await app.inject({ method: 'GET', url: '/api/backups', ...auth(cookie) })
+    expect(list.json().backups).toHaveLength(1)
+    expect(list.json().backups[0].file).toMatch(/\.db$/)
+    await app.close()
+  })
+
+  it('prunes to the newest 7 backups', async () => {
+    const app = await buildTestApp()
+    const cookie = await setupAdmin(app)
+    for (let i = 0; i < 9; i++) {
+      await app.inject({ method: 'POST', url: '/api/backup', ...auth(cookie) })
+    }
+    const list = await app.inject({ method: 'GET', url: '/api/backups', ...auth(cookie) })
+    expect(list.json().backups).toHaveLength(7)
+    await app.close()
+  })
+})
+```
+
+Note: `/api/collection/1/loan` against a fresh app (no items) returns 404 — the `.catch(() => {})` guard on inject is wrong (inject doesn't reject); just fire it without the catch and ignore the status, or drop that call — export asserts empty arrays anyway. Simplify: remove the loan call from `appWithData`.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run server/test/data.test.ts`
+Expected: FAIL — 404s.
+
+- [ ] **Step 3: Create `server/src/routes/dataRoutes.ts`** — full file:
+
+```ts
+import { FastifyInstance } from 'fastify'
+import { readdirSync, statSync, unlinkSync } from 'node:fs'
+import path from 'node:path'
+import { requireAuth, requireAdmin } from './authRoutes.js'
+
+function matchLinksFor(db: any, userId: number) {
+  return db
+    .prepare(
+      `SELECT ml.item_id AS itemId, ml.album_id AS albumId FROM match_links ml WHERE ml.user_id = ?`
+    )
+    .all(userId)
+}
+
+function listBackups(dir: string): { file: string; sizeBytes: number; createdAt: string }[] {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.db'))
+      .map((file) => {
+        const full = path.join(dir, file)
+        const st = statSync(full)
+        return { file, sizeBytes: st.size, createdAt: st.mtime.toISOString() }
+      })
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+  } catch {
+    return []
+  }
+}
+
+export async function registerDataRoutes(app: FastifyInstance): Promise<void> {
+  app.get('/api/export', { preHandler: [requireAuth] }, async (request) => {
+    const db = request.server.db
+    const userId = request.user.id
+    const items = db
+      .prepare('SELECT * FROM collection_items WHERE user_id = ? ORDER BY date_added')
+      .all(userId)
+    const loans = db.prepare('SELECT * FROM loans WHERE user_id = ?').all(userId)
+    return {
+      exportedAt: new Date().toISOString(),
+      items,
+      loans,
+      matchLinks: matchLinksFor(db, userId),
+    }
+  })
+
+  app.post('/api/backup', { preHandler: [requireAuth, requireAdmin] }, async (request, reply) => {
+    const config = request.server.config
+    const stamp = new Date().toISOString().replace(/[:T]/g, '-').slice(0, 19)
+    const dest = path.join(config.backupsDir, `record-shop-${stamp}.db`)
+    await request.server.db.backup(dest)
+    // prune to newest 7
+    const backups = listBackups(config.backupsDir)
+    for (const old of backups.slice(7)) {
+      try {
+        unlinkSync(path.join(config.backupsDir, old.file))
+      } catch {
+        // best-effort prune
+      }
+    }
+    return { file: path.basename(dest) }
+  })
+
+  app.get('/api/backups', { preHandler: [requireAuth, requireAdmin] }, async (request) => {
+    return { backups: listBackups(request.server.config.backupsDir) }
+  })
+}
+```
+
+Note: `/api/export` returns raw rows (snake_case, internal ids) — intentional: it's a backup artifact, not a UI payload. Tests assert shape only.
+
+- [ ] **Step 4: Register in `server/src/app.ts`** — import + `await registerDataRoutes(app)` after `registerStatsRoutes(app)`.
+
+- [ ] **Step 5: Run tests**
+
+Run: `npx vitest run server/test/data.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS (163 + 4 new = 167).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A && git commit -m "feat: json export and sqlite backup endpoints"
+```
+
+---
+
+### Task 8: Web — types + api client additions
+
+**Files:**
+- Modify: `web/src/types.ts`, `web/src/api.ts`
+- Test: `web/test/api.test.ts` (new, thin — URL/shape checks via fetch stub)
+
+- [ ] **Step 1: Add types to `web/src/types.ts`** (append):
+
+```ts
+export interface Track {
+  id: string
+  title: string
+  duration: number | null
+  track: number | null
+}
+export interface AlbumTracks {
+  id: string
+  title: string
+  artist: string
+  tracks: Track[]
+}
+export interface MatchedAlbum {
+  id: number
+  subsonicId: string
+  lastPlayedAt: string | null
+}
+export interface Stats {
+  totals: { items: number; ripped: number; notRipped: number; onLoan: number }
+  ripRatio: number
+  formats: { name: string; count: number }[]
+  decades: { name: string; count: number }[]
+  topGenres: { name: string; count: number }[]
+  topArtists: { name: string; count: number }[]
+  addedByMonth: { month: string; count: number }[]
+}
+export interface Loan {
+  id: number
+  itemId: number
+  borrower: string
+  lentAt: string
+  returnedAt: string | null
+}
+export interface LoansResponse {
+  active: Loan[]
+  history: Loan[]
+}
+export interface BackupFile {
+  file: string
+  sizeBytes: number
+  createdAt: string
+}
+```
+
+- [ ] **Step 2: Modify `web/src/api.ts`** — extend the imports (`type { …, Track is not needed here }`, add `AlbumTracks, Loan, LoansResponse, Stats, BackupFile`) and append methods to the `api` object:
+
+```ts
+  getAlbumTracks: (subsonicId: string) => request<AlbumTracks>(`/api/album/${encodeURIComponent(subsonicId)}/tracks`),
+  markPlayed: (subsonicId: string) => post<{ ok: boolean }>(`/api/album/${encodeURIComponent(subsonicId)}/played`),
+  streamUrl: (songId: string) => `/api/stream/${encodeURIComponent(songId)}`,
+
+  getStats: () => request<Stats>('/api/stats'),
+  exportUrl: () => '/api/export',
+
+  lendItem: (id: number, borrower: string) => post<Loan>(`/api/collection/${id}/loan`, { borrower }),
+  getLoans: () => request<LoansResponse>('/api/loans'),
+  returnLoan: (id: number) => post<{ ok: boolean }>(`/api/loans/${id}/return`),
+
+  triggerBackup: () => post<{ file: string }>('/api/backup'),
+  getBackups: () => request<{ backups: BackupFile[] }>('/api/backups'),
+```
+
+Also change `getItem`'s return type: `request<Item & { matchedAlbum: MatchedAlbum | null }>` (or add a `MatchedAlbum` import and use `ItemDetail` alias — define `export interface ItemDetail extends Item { matchedAlbum: MatchedAlbum | null }` in types.ts and use it in api.ts).
+
+Also `listCollection` params gain `onLoan?: string`:
+```ts
+    if (params.onLoan) usp.set('onLoan', params.onLoan)
+```
+
+- [ ] **Step 3: Write `web/test/api.test.ts`** (thin — stub fetch, assert URLs and error mapping):
+
+```ts
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { api, ApiError } from '../src/api.js'
+
+const fetchMock = vi.fn()
+beforeEach(() => vi.stubGlobal('fetch', fetchMock))
+afterEach(() => vi.unstubAllGlobals())
+
+function jsonOk(body: unknown) {
+  return Promise.resolve(new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } }))
+}
+
+describe('api additions', () => {
+  it('album tracks + played + stream url', async () => {
+    fetchMock.mockReturnValue(jsonOk({ id: 'a1', title: 'Motion', artist: 'TCO', tracks: [] }))
+    await api.getAlbumTracks('a1')
+    expect(fetchMock).toHaveBeenCalledWith('/api/album/a1/tracks', expect.anything())
+    await api.markPlayed('a1')
+    expect(fetchMock).toHaveBeenCalledWith('/api/album/a1/played', expect.objectContaining({ method: 'POST' }))
+    expect(api.streamUrl('s 1')).toBe('/api/stream/s%201')
+  })
+
+  it('stats, loans, backups urls', async () => {
+    fetchMock.mockReturnValue(jsonOk({}))
+    await api.getStats()
+    expect(fetchMock).toHaveBeenCalledWith('/api/stats', expect.anything())
+    await api.lendItem(5, 'Bob')
+    expect(fetchMock).toHaveBeenCalledWith('/api/collection/5/loan', expect.objectContaining({ method: 'POST' }))
+    await api.returnLoan(7)
+    expect(fetchMock).toHaveBeenCalledWith('/api/loans/7/return', expect.objectContaining({ method: 'POST' }))
+    await api.getBackups()
+    expect(fetchMock).toHaveBeenCalledWith('/api/backups', expect.anything())
+    expect(api.exportUrl()).toBe('/api/export')
+  })
+
+  it('surfaces subsonic errors as ApiError', async () => {
+    fetchMock.mockReturnValue(
+      Promise.resolve(new Response(JSON.stringify({ error: 'no_subsonic_config' }), { status: 409 }))
+    )
+    const err = await api.getAlbumTracks('a1').catch((e) => e)
+    expect(err).toBeInstanceOf(ApiError)
+    expect((err as ApiError).code).toBe('no_subsonic_config')
+  })
+})
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `npx vitest run web/test/api.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS (167 + 3 new = 170). Existing page tests that mock the api module keep working (spread of actual).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A && git commit -m "feat: web api client additions for wave 1"
+```
+
+---
+
+### Task 9: Player context + reducer + audio element
+
+**Files:**
+- Create: `web/src/player/PlayerContext.tsx`
+- Test: `web/test/player.test.tsx`
+
+- [ ] **Step 1: Write the failing test `web/test/player.test.tsx`**
+
+```tsx
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { PlayerProvider, usePlayer } from '../src/player/PlayerContext.js'
+import type { Track } from '../src/types.js'
+
+vi.mock('../src/api.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/api.js')>()
+  return { ...actual, api: { ...actual.api, getAlbumTracks: vi.fn(), markPlayed: vi.fn() } }
+})
+
+import { api } from '../src/api.js'
+
+const tracks: Track[] = [
+  { id: 's1', title: 'Overture', duration: 200, track: 1 },
+  { id: 's2', title: 'Theme de Yoyo', duration: 300, track: 2 },
+]
+
+function Probe() {
+  const { state, load, toggle, next, prev, close } = usePlayer()
+  return (
+    <div>
+      <div>phase:{state.album ? (state.playing ? 'playing' : 'paused') : 'empty'}</div>
+      <div>track:{state.tracks[state.index]?.title ?? 'none'}</div>
+      <button type="button" onClick={() => load({ id: 'a1', title: 'Motion', artist: 'TCO' })}>load</button>
+      <button type="button" onClick={() => toggle()}>toggle</button>
+      <button type="button" onClick={() => next()}>next</button>
+      <button type="button" onClick={() => prev()}>prev</button>
+      <button type="button" onClick={() => close()}>close</button>
+    </div>
+  )
+}
+
+function renderPlayer() {
+  return render(
+    <PlayerProvider>
+      <Probe />
+    </PlayerProvider>
+  )
+}
+
+describe('PlayerProvider', () => {
+  it('loads a queue, stamps played, starts at track 1', async () => {
+    vi.mocked(api.getAlbumTracks).mockResolvedValue({ id: 'a1', title: 'Motion', artist: 'TCO', tracks } as never)
+    vi.mocked(api.markPlayed).mockResolvedValue({ ok: true } as never)
+    renderPlayer()
+    await userEvent.click(screen.getByRole('button', { name: 'load' }))
+    await waitFor(() => expect(screen.getByText('phase:playing')).toBeTruthy())
+    expect(screen.getByText('track:Overture')).toBeTruthy()
+    expect(api.getAlbumTracks).toHaveBeenCalledWith('a1')
+    expect(api.markPlayed).toHaveBeenCalledWith('a1')
+  })
+
+  it('toggle pauses and resumes', async () => {
+    vi.mocked(api.getAlbumTracks).mockResolvedValue({ id: 'a1', title: 'Motion', artist: 'TCO', tracks } as never)
+    vi.mocked(api.markPlayed).mockResolvedValue({ ok: true } as never)
+    renderPlayer()
+    await userEvent.click(screen.getByRole('button', { name: 'load' }))
+    await waitFor(() => expect(screen.getByText('phase:playing')).toBeTruthy())
+    await userEvent.click(screen.getByRole('button', { name: 'toggle' }))
+    expect(screen.getByText('phase:paused')).toBeTruthy()
+    await userEvent.click(screen.getByRole('button', { name: 'toggle' }))
+    expect(screen.getByText('phase:playing')).toBeTruthy()
+  })
+
+  it('next/prev move through the queue and stop at the edges', async () => {
+    vi.mocked(api.getAlbumTracks).mockResolvedValue({ id: 'a1', title: 'Motion', artist: 'TCO', tracks } as never)
+    vi.mocked(api.markPlayed).mockResolvedValue({ ok: true } as never)
+    renderPlayer()
+    await userEvent.click(screen.getByRole('button', { name: 'load' }))
+    await waitFor(() => expect(screen.getByText('track:Overture')).toBeTruthy())
+    await userEvent.click(screen.getByRole('button', { name: 'next' }))
+    expect(screen.getByText('track:Theme de Yoyo')).toBeTruthy()
+    await userEvent.click(screen.getByRole('button', { name: 'next' }))
+    expect(screen.getByText('track:Theme de Yoyo')).toBeTruthy() // last track: no advance
+    await userEvent.click(screen.getByRole('button', { name: 'prev' }))
+    expect(screen.getByText('track:Overture')).toBeTruthy()
+    await userEvent.click(screen.getByRole('button', { name: 'prev' }))
+    expect(screen.getByText('track:Overture')).toBeTruthy() // first track: no rewind
+  })
+
+  it('close empties the player', async () => {
+    vi.mocked(api.getAlbumTracks).mockResolvedValue({ id: 'a1', title: 'Motion', artist: 'TCO', tracks } as never)
+    vi.mocked(api.markPlayed).mockResolvedValue({ ok: true } as never)
+    renderPlayer()
+    await userEvent.click(screen.getByRole('button', { name: 'load' }))
+    await waitFor(() => expect(screen.getByText('phase:playing')).toBeTruthy())
+    await userEvent.click(screen.getByRole('button', { name: 'close' }))
+    expect(screen.getByText('phase:empty')).toBeTruthy()
+  })
+
+  it('audio error marks the track failed and skips to the next', async () => {
+    vi.mocked(api.getAlbumTracks).mockResolvedValue({ id: 'a1', title: 'Motion', artist: 'TCO', tracks } as never)
+    vi.mocked(api.markPlayed).mockResolvedValue({ ok: true } as never)
+    renderPlayer()
+    await userEvent.click(screen.getByRole('button', { name: 'load' }))
+    await waitFor(() => expect(screen.getByText('track:Overture')).toBeTruthy())
+    act(() => {
+      document.querySelector('audio')!.dispatchEvent(new Event('error'))
+    })
+    await waitFor(() => expect(screen.getByText('track:Theme de Yoyo')).toBeTruthy())
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run web/test/player.test.tsx`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Create `web/src/player/PlayerContext.tsx`** — full file:
+
+```tsx
+import { createContext, useContext, useEffect, useReducer, useCallback, type ReactNode } from 'react'
+import { api } from '../api.js'
+import type { Track } from '../types.js'
+
+export interface PlayerAlbum {
+  id: string
+  title: string
+  artist: string
+}
+
+export interface PlayerState {
+  album: PlayerAlbum | null
+  tracks: Track[]
+  index: number
+  playing: boolean
+  failed: number[]
+}
+
+type PlayerAction =
+  | { type: 'LOAD'; album: PlayerAlbum; tracks: Track[] }
+  | { type: 'TOGGLE' }
+  | { type: 'NEXT' }
+  | { type: 'PREV' }
+  | { type: 'TRACK_ERROR' }
+  | { type: 'CLOSE' }
+
+const INITIAL: PlayerState = { album: null, tracks: [], index: 0, playing: false, failed: [] }
+
+export function playerReducer(state: PlayerState, action: PlayerAction): PlayerState {
+  switch (action.type) {
+    case 'LOAD':
+      return { album: action.album, tracks: action.tracks, index: 0, playing: action.tracks.length > 0, failed: [] }
+    case 'TOGGLE':
+      return { ...state, playing: !state.playing }
+    case 'NEXT':
+      return state.index < state.tracks.length - 1 ? { ...state, index: state.index + 1, playing: true } : { ...state, playing: false }
+    case 'PREV':
+      return state.index > 0 ? { ...state, index: state.index - 1, playing: true } : state
+    case 'TRACK_ERROR':
+      return {
+        ...state,
+        failed: state.failed.includes(state.index) ? state.failed : [...state.failed, state.index],
+        ...(state.index < state.tracks.length - 1 ? { index: state.index + 1, playing: true } : { playing: false }),
+      }
+    case 'CLOSE':
+      return INITIAL
+  }
+}
+
+interface PlayerContextValue {
+  state: PlayerState
+  load: (album: PlayerAlbum) => Promise<void>
+  toggle: () => void
+  next: () => void
+  prev: () => void
+  close: () => void
+}
+
+const PlayerContext = createContext<PlayerContextValue | null>(null)
+
+export function PlayerProvider({ children }: { children: ReactNode }) {
+  const [state, dispatch] = useReducer(playerReducer, INITIAL)
+
+  const load = useCallback(async (album: PlayerAlbum) => {
+    const data = await api.getAlbumTracks(album.id)
+    dispatch({ type: 'LOAD', album: { id: data.id, title: data.title, artist: data.artist }, tracks: data.tracks })
+    void api.markPlayed(album.id).catch(() => {})
+  }, [])
+
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+  const current = state.tracks[state.index]
+
+  // keep the single audio element in sync with the reducer
+  useEffect(() => {
+    const audio = audioRef.current
+    if (!audio) return
+    if (!current) {
+      audio.pause()
+      audio.removeAttribute('src')
+      return
+    }
+    const wanted = api.streamUrl(current.id)
+    if (!audio.src.endsWith(wanted)) audio.src = wanted
+    if (state.playing) void audio.play().catch(() => {})
+    else audio.pause()
+  }, [current, state.playing])
+
+  const onEnded = useCallback(() => dispatch({ type: 'NEXT' }), [])
+  const onError = useCallback(() => dispatch({ type: 'TRACK_ERROR' }), [])
+  const toggle = useCallback(() => dispatch({ type: 'TOGGLE' }), [])
+  const next = useCallback(() => dispatch({ type: 'NEXT' }), [])
+  const prev = useCallback(() => dispatch({ type: 'PREV' }), [])
+  const close = useCallback(() => dispatch({ type: 'CLOSE' }), [])
+
+  return (
+    <PlayerContext.Provider value={{ state, load, toggle, next, prev, close }}>
+      {children}
+      <audio ref={audioRef} onEnded={onEnded} onError={onError} preload="none" />
+    </PlayerContext.Provider>
+  )
+}
+
+export function usePlayer(): PlayerContextValue {
+  const ctx = useContext(PlayerContext)
+  if (!ctx) throw new Error('usePlayer outside PlayerProvider')
+  return ctx
+}
+```
+
+Add `useRef` to the react import. jsdom caveat: `HTMLMediaElement.play` is not implemented — `vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue()` in the test file's top-level `beforeEach` (the scanner test already uses this pattern); also mock `pause`.
+
+- [ ] **Step 4: Run tests**
+
+Run: `npx vitest run web/test/player.test.tsx && npm test && npm run typecheck`
+Expected: ALL PASS (170 + 5 new = 175).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A && git commit -m "feat: global player context with album queue and audio element"
+```
+
+---
+
+### Task 10: MiniBar + expanded player, wired into the shell
+
+**Files:**
+- Create: `web/src/player/MiniBar.tsx`
+- Modify: `web/src/App.tsx` (wrap routes with PlayerProvider inside AuthProvider; render MiniBar inside the protected shell)
+- Test: `web/test/minibar.test.tsx`
+
+- [ ] **Step 1: Write the failing test `web/test/minibar.test.tsx`**
+
+```tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { PlayerProvider, usePlayer } from '../src/player/PlayerContext.js'
+import MiniBar from '../src/player/MiniBar.js'
+import type { Track } from '../src/types.js'
+
+vi.mock('../src/api.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/api.js')>()
+  return { ...actual, api: { ...actual.api, getAlbumTracks: vi.fn(), markPlayed: vi.fn() } }
+})
+import { api } from '../src/api.js'
+
+const tracks: Track[] = [
+  { id: 's1', title: 'Overture', duration: 200, track: 1 },
+  { id: 's2', title: 'Theme de Yoyo', duration: 300, track: 2 },
+]
+
+function Loader() {
+  const { load } = usePlayer()
+  return (
+    <button type="button" onClick={() => void load({ id: 'a1', title: 'Motion', artist: 'TCO' })}>
+      load
+    </button>
+  )
+}
+
+beforeEach(() => {
+  vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue()
+  vi.spyOn(HTMLMediaElement.prototype, 'pause').mockReturnValue(undefined)
+  vi.mocked(api.getAlbumTracks).mockResolvedValue({ id: 'a1', title: 'Motion', artist: 'TCO', tracks } as never)
+  vi.mocked(api.markPlayed).mockResolvedValue({ ok: true } as never)
+})
+
+function renderBar() {
+  return render(
+    <PlayerProvider>
+      <Loader />
+      <MiniBar />
+    </PlayerProvider>
+  )
+}
+
+describe('MiniBar', () => {
+  it('hidden when nothing is loaded, shows controls when playing', async () => {
+    renderBar()
+    expect(screen.queryByRole('button', { name: /play or pause/i })).toBeNull()
+    await userEvent.click(screen.getByRole('button', { name: 'load' }))
+    await waitFor(() => expect(screen.getByText('Motion')).toBeTruthy())
+    expect(screen.getByRole('button', { name: /pause/i })).toBeTruthy()
+  })
+
+  it('pause/resume works from the bar', async () => {
+    renderBar()
+    await userEvent.click(screen.getByRole('button', { name: 'load' }))
+    const pauseBtn = await screen.findByRole('button', { name: /pause/i })
+    await userEvent.click(pauseBtn)
+    expect(screen.getByRole('button', { name: /play/i })).toBeTruthy()
+  })
+
+  it('expands to the track list and closes', async () => {
+    renderBar()
+    await userEvent.click(screen.getByRole('button', { name: 'load' }))
+    await userEvent.click(await screen.findByRole('button', { name: /expand/i }))
+    expect(screen.getByText('Theme de Yoyo')).toBeTruthy()
+    expect(screen.getByText('Overture')).toBeTruthy()
+    await userEvent.click(screen.getByRole('button', { name: /collapse/i }))
+    expect(screen.queryByText('Theme de Yoyo')).toBeNull()
+    await userEvent.click(screen.getByRole('button', { name: /close player/i }))
+    await waitFor(() => expect(screen.queryByText('Motion')).toBeNull())
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run web/test/minibar.test.tsx`
+Expected: FAIL — MiniBar not found.
+
+- [ ] **Step 3: Create `web/src/player/MiniBar.tsx`** — full file:
+
+```tsx
+import { useState } from 'react'
+import { usePlayer } from './PlayerContext.js'
+import Cover from '../components/Cover.js'
+
+export default function MiniBar() {
+  const { state, toggle, next, prev, close } = usePlayer()
+  const [expanded, setExpanded] = useState(false)
+  if (!state.album) return null
+
+  const current = state.tracks[state.index]
+
+  if (expanded) {
+    return (
+      <div className="fixed inset-x-0 bottom-16 z-20 mx-auto max-w-3xl rounded-t-2xl border border-neutral-700 bg-neutral-900 p-4">
+        <div className="flex items-center justify-between">
+          <div className="min-w-0">
+            <p className="truncate font-medium">{state.album.title}</p>
+            <p className="truncate text-sm text-neutral-400">{state.album.artist}</p>
+          </div>
+          <div className="flex gap-2">
+            <button type="button" onClick={() => setExpanded(false)} aria-label="collapse player" className="text-neutral-400">
+              ▾
+            </button>
+            <button type="button" onClick={close} aria-label="close player" className="text-neutral-400">
+              ✕
+            </button>
+          </div>
+        </div>
+        <ol className="mt-3 max-h-64 space-y-1 overflow-y-auto text-sm">
+          {state.tracks.map((t, i) => (
+            <li
+              key={t.id}
+              className={`flex justify-between rounded-lg px-2 py-1 ${i === state.index ? 'bg-neutral-800 text-emerald-400' : 'text-neutral-300'}`}
+            >
+              <span className="truncate">
+                {t.track ?? i + 1}. {t.title}
+              </span>
+              {t.duration != null && <span className="ml-2 shrink-0 text-neutral-500">{Math.floor(t.duration / 60)}:{String(t.duration % 60).padStart(2, '0')}</span>}
+            </li>
+          ))}
+        </ol>
+      </div>
+    )
+  }
+
+  return (
+    <div className="fixed inset-x-0 bottom-16 z-20 mx-auto max-w-3xl px-4">
+      <div className="flex items-center gap-3 rounded-2xl border border-neutral-700 bg-neutral-900/95 p-2 shadow-lg backdrop-blur">
+        <button type="button" onClick={() => setExpanded(true)} aria-label="expand player" className="shrink-0">
+          <Cover src={null} alt="" className="size-10" />
+        </button>
+        <div className="min-w-0 flex-1">
+          <p className="truncate text-sm font-medium">{current?.title}</p>
+          <p className="truncate text-xs text-neutral-400">{state.album.title}</p>
+        </div>
+        <button type="button" onClick={prev} aria-label="previous track" className="px-1 text-neutral-300">
+          ⏮
+        </button>
+        <button
+          type="button"
+          onClick={toggle}
+          aria-label={state.playing ? 'pause' : 'play'}
+          className="rounded-full bg-emerald-500 px-3 py-1.5 text-neutral-950"
+        >
+          {state.playing ? '⏸' : '▶'}
+        </button>
+        <button type="button" onClick={next} aria-label="next track" className="px-1 text-neutral-300">
+          ⏭
+        </button>
+        <button type="button" onClick={close} aria-label="close player" className="px-1 text-neutral-500">
+          ✕
+        </button>
+      </div>
+    </div>
+  )
+}
+```
+
+(A seek bar is deferred: the audio element's seek needs ref plumbing between MiniBar and the provider's audio element. The spec's mini-bar lists seek — note in the task report if omitted, or implement via `usePlayer()` gaining `seek(t: number)` + a `currentTimeRef` — coordinator decision: seek lands with the expanded player in a follow-up fix if the simple version feels incomplete. Prefer shipping the above and adding seek during review if trivial.)
+
+- [ ] **Step 4: Modify `web/src/App.tsx`** — wrap with PlayerProvider and render MiniBar:
+
+```tsx
+import { PlayerProvider } from './player/PlayerContext.js'
+import MiniBar from './player/MiniBar.js'
+```
+- Outermost: `<AuthProvider>...` stays; inside it wrap the whole `<BrowserRouter>` content with `<PlayerProvider>`; render `<MiniBar />` inside the protected layout route element, after `<Shell />`:
+
+```tsx
+          <Route
+            element={
+              <Gate>
+                <PlayerProvider>
+                  <Shell />
+                  <MiniBar />
+                </PlayerProvider>
+              </Gate>
+            }
+          >
+```
+(The audio element lives in PlayerProvider; rendering MiniBar inside the same provider gives it context access. Keep `<audio>` in the provider — it renders nothing visible.)
+
+- [ ] **Step 5: Run tests**
+
+Run: `npx vitest run web/test/minibar.test.tsx && npm test && npm run typecheck`
+Expected: ALL PASS (175 + 3 new = 178). Existing router tests render App — PlayerProvider mounts an `<audio>` element in jsdom (harmless); MiniBar hidden without a queue.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A && git commit -m "feat: mini player bar with expandable track list"
+```
+
+---
+
+### Task 11: Item page — Play, last played, loans
+
+**Files:**
+- Modify: `web/src/pages/ItemPage.tsx`
+- Test: `web/test/item.test.tsx` (append)
+
+- [ ] **Step 1: Append failing tests to `web/test/item.test.tsx`**
+
+The file's existing mocks: api module with getItem/setRip/setMatch/deleteItem/searchAlbums. Add getAlbumTracks/markPlayed/lendItem/getLoans/returnLoan to the override list; `getItem` fixture gains `matchedAlbum`:
+
+```tsx
+import type { Item, MatchedAlbum } from '../src/types.js'
+
+const matched: MatchedAlbum = { id: 77, subsonicId: 'alb-1', lastPlayedAt: '2026-09-01T10:00:00Z' }
+const rippedItem: Item = { ...item, ripStatus: 'ripped', matchedAlbum: matched }
+```
+
+(Adjust the base `item` fixture: it must now carry `matchedAlbum: null` so existing tests keep passing; the default `getItem` mock resolves the base item.)
+
+```tsx
+  it('shows Play for a ripped item with a matched album and loads the player', async () => {
+    vi.mocked(api.getItem).mockResolvedValue(rippedItem as never)
+    vi.mocked(api.getAlbumTracks).mockResolvedValue({ id: 'alb-1', title: 'Motion', artist: 'TCO', tracks: [] } as never)
+    vi.mocked(api.markPlayed).mockResolvedValue({ ok: true } as never)
+    renderItem()
+    const play = await screen.findByRole('button', { name: /play album/i })
+    await userEvent.click(play)
+    await waitFor(() => expect(api.getAlbumTracks).toHaveBeenCalledWith('alb-1'))
+    await waitFor(() => expect(api.markPlayed).toHaveBeenCalledWith('alb-1'))
+  })
+
+  it('hides Play when unmatched or not ripped', async () => {
+    vi.mocked(api.getItem).mockResolvedValue(item as never) // not ripped, matchedAlbum null
+    renderItem()
+    await waitFor(() => expect(screen.getByRole('heading', { name: 'Motion' })).toBeTruthy())
+    expect(screen.queryByRole('button', { name: /play album/i })).toBeNull()
+  })
+
+  it('shows last played under the rip banner', async () => {
+    vi.mocked(api.getItem).mockResolvedValue(rippedItem as never)
+    renderItem()
+    expect(await screen.findByText(/last played/i)).toBeTruthy()
+  })
+
+  it('lend and return flow', async () => {
+    vi.mocked(api.getItem).mockResolvedValue(rippedItem as never)
+    vi.mocked(api.lendItem).mockResolvedValue({ id: 9, itemId: 1, borrower: 'Bob', lentAt: '2026-09-03', returnedAt: null } as never)
+    renderItem()
+    await userEvent.type(await screen.findByLabelText(/borrower/i), 'Bob')
+    await userEvent.click(screen.getByRole('button', { name: /^lend$/i }))
+    await waitFor(() => expect(api.lendItem).toHaveBeenCalledWith(1, 'Bob'))
+    await waitFor(() => expect(screen.getByText(/out to bob/i)).toBeTruthy())
+
+    vi.mocked(api.returnLoan).mockResolvedValue({ ok: true } as never)
+    vi.mocked(api.getItem).mockResolvedValue({ ...rippedItem } as never)
+    await userEvent.click(screen.getByRole('button', { name: /mark returned/i }))
+    await waitFor(() => expect(api.returnLoan).toHaveBeenCalledWith(9))
+  })
+```
+
+(The lend flow's second phase needs the item's loan state — the page re-fetches the item after lend (`getItem` again) and shows 'Out to Bob…' + 'Mark returned' when `loan` present. See implementation: the detail response gains `loan: Loan | null` — ADD to the backend detail route in this task: `loan: activeLoanFor(db, row.id)` where `activeLoanFor` queries `loans WHERE item_id = ? AND returned_at IS NULL`. That is a small backend addition folded here: modify `server/src/routes/collectionRoutes.ts` detail route to include `loan`, and extend the backend test in `server/test/loans.test.ts` asserting `detail.json().loan` after lending.)
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run web/test/item.test.tsx`
+Expected: FAIL — no Play/loan UI.
+
+- [ ] **Step 3: Implement**
+
+Backend first — `server/src/routes/collectionRoutes.ts` detail route returns `loan` too:
+```ts
+    const loan = db
+      .prepare('SELECT id, borrower, lent_at FROM loans WHERE item_id = ? AND returned_at IS NULL')
+      .get(row.id) as { id: number; borrower: string; lent_at: string } | undefined
+    return {
+      ...rowToItem(db, row),
+      matchedAlbum: findMatchedAlbum(db, request.user.id, row.id),
+      loan: loan ? { id: loan.id, borrower: loan.borrower, lentAt: loan.lent_at } : null,
+    }
+```
+(+ backend test assertion in loans.test.ts; type `ItemDetail` in web/src/types.ts gains `loan: { id: number; borrower: string; lentAt: string } | null`.)
+
+Frontend — in `web/src/pages/ItemPage.tsx`:
+- Type the item state as `ItemDetail | null`
+- After the rip banner, before the toggle buttons:
+```tsx
+      {item.ripStatus === 'ripped' && item.matchedAlbum && (
+        <button
+          type="button"
+          onClick={() => void load({ id: item.matchedAlbum!.subsonicId, title: item.title, artist: item.artist })}
+          className="w-full rounded-xl bg-emerald-500 py-2.5 font-medium text-neutral-950"
+        >
+          ▶ Play album
+        </button>
+      )}
+      {item.matchedAlbum?.lastPlayedAt && (
+        <p className="text-xs text-neutral-500">Last played {timeAgo(item.matchedAlbum.lastPlayedAt)}</p>
+      )}
+```
+- `load` from `usePlayer()`; `timeAgo(iso)` — small local helper (minutes/hours/days/months/years, 'just now' < 60s); define in the file.
+- Loan section (after re-match section):
+```tsx
+      <section className="rounded-xl border border-neutral-800 bg-neutral-900 p-3">
+        {item.loan ? (
+          <div className="flex items-center justify-between">
+            <p className="text-sm text-neutral-300">
+              Out to {item.loan.borrower} since {new Date(item.loan.lentAt).toLocaleDateString()}
+            </p>
+            <button
+              type="button"
+              onClick={() => void api.returnLoan(item.loan!.id).then(() => refetch())}
+              className="rounded-lg border border-neutral-700 px-3 py-1.5 text-sm text-neutral-300"
+            >
+              Mark returned
+            </button>
+          </div>
+        ) : (
+          <form
+            onSubmit={(e) => {
+              e.preventDefault()
+              if (!item) return
+              const borrower = (e.currentTarget.elements.namedItem('borrower') as HTMLInputElement).value
+              void api.lendItem(item.id, borrower).then(() => refetch())
+            }}
+            className="flex gap-2"
+          >
+            <input
+              name="borrower"
+              aria-label="Borrower"
+              placeholder="Lend to…"
+              required
+              className="min-w-0 flex-1 rounded-lg border border-neutral-700 bg-neutral-950 px-3 py-1.5 text-sm"
+            />
+            <button type="submit" className="rounded-lg border border-neutral-700 px-3 py-1.5 text-sm text-neutral-300">
+              Lend
+            </button>
+          </form>
+        )}
+      </section>
+```
+- `refetch()` = re-run `api.getItem(Number(id)).then(setItem)` — extract the load into a `refetch` callback used by the mount effect too.
+
+- [ ] **Step 4: Run tests**
+
+Run: `npx vitest run web/test/item.test.tsx server/test/loans.test.ts && npm test && npm run typecheck`
+Expected: ALL PASS (178 + 4 new = 182).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A && git commit -m "feat: play button, last played, loan lend/return on item page"
+```
+
+---
+
+### Task 12: Library links + On-loan chip; Queue page
+
+**Files:**
+- Modify: `web/src/pages/LibraryPage.tsx`, `web/src/App.tsx`
+- Create: `web/src/pages/QueuePage.tsx`
+- Test: `web/test/library.test.tsx` (append), `web/test/queue.test.tsx` (new)
+
+- [ ] **Step 1: Append failing tests to `web/test/library.test.tsx`**
+
+```tsx
+  it('header links to stats and queue', async () => {
+    renderLibrary()
+    await waitFor(() => expect(screen.getByRole('link', { name: /stats/i })).toHaveProperty('href'))
+    expect(screen.getByRole('link', { name: /queue/i })).toBeTruthy()
+  })
+
+  it('on-loan chip filters by loan state', async () => {
+    renderLibrary()
+    await waitFor(() => expect(screen.getByRole('button', { name: /^on loan$/i })).toBeTruthy())
+    await userEvent.click(screen.getByRole('button', { name: /^on loan$/i }))
+    await waitFor(() =>
+      expect(api.listCollection).toHaveBeenLastCalledWith(expect.objectContaining({ onLoan: 'true' }))
+    )
+    await userEvent.click(screen.getByRole('button', { name: /^on loan$/i }))
+    await waitFor(() =>
+      expect(api.listCollection).toHaveBeenLastCalledWith(expect.not.objectContaining({ onLoan: expect.anything() }))
+    )
+  })
+```
+(The plan's `toHaveProperty('href')` pattern from earlier tasks applies — use the file's existing link-assertion style.)
+
+- [ ] **Step 2: Write the failing test `web/test/queue.test.tsx`**
+
+```tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { MemoryRouter } from 'react-router-dom'
+import QueuePage from '../src/pages/QueuePage.js'
+import type { Item } from '../src/types.js'
+
+vi.mock('../src/api.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/api.js')>()
+  return { ...actual, api: { ...actual.api, listCollection: vi.fn(), setRip: vi.fn() } }
+})
+import { api } from '../src/api.js'
+
+function qItem(id: number, title: string, added: string): Item {
+  return {
+    id, discogsReleaseId: 1, title, artist: 'Artist', year: 1999, formats: ['CD'], genres: [], labels: [],
+    tracklist: [], catno: null, country: null, artworkUrl: null, barcodes: [], dateAdded: added,
+    ripOverride: null, ripStatus: 'not_ripped',
+  }
+}
+
+beforeEach(() => {
+  vi.mocked(api.listCollection).mockReset()
+  vi.mocked(api.setRip).mockReset()
+})
+
+describe('QueuePage', () => {
+  it('lists not-ripped items oldest first and marks ripped', async () => {
+    vi.mocked(api.listCollection).mockResolvedValue({
+      items: [qItem(1, 'Newest', '2026-08-20'), qItem(2, 'Oldest', '2026-08-01')],
+      counts: { total: 2, ripped: 0, notRipped: 2 },
+    } as never)
+    vi.mocked(api.setRip).mockResolvedValue({} as never)
+    render(
+      <MemoryRouter>
+        <QueuePage />
+      </MemoryRouter>
+    )
+    expect(await screen.findByText('Oldest')).toBeTruthy() // oldest first
+    const rows = screen.getAllByRole('button', { name: /mark ripped/i })
+    await userEvent.click(rows[0]!)
+    await waitFor(() => expect(api.setRip).toHaveBeenCalledWith(2, true))
+    await waitFor(() => expect(screen.queryByText('Oldest')).toBeNull())
+  })
+
+  it('empty state points back to scanning', async () => {
+    vi.mocked(api.listCollection).mockResolvedValue({ items: [], counts: { total: 0, ripped: 0, notRipped: 0 } } as never)
+    render(
+      <MemoryRouter>
+        <QueuePage />
+      </MemoryRouter>
+    )
+    expect(await screen.findByText(/nothing waiting/i)).toBeTruthy()
+  })
+})
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `npx vitest run web/test/library.test.tsx web/test/queue.test.tsx`
+Expected: FAIL — no header links, no QueuePage.
+
+- [ ] **Step 4: Implement**
+
+`web/src/pages/QueuePage.tsx` — full file:
+```tsx
+import { useEffect, useState } from 'react'
+import { Link } from 'react-router-dom'
+import { api } from '../api.js'
+import type { Item } from '../types.js'
+import Cover from '../components/Cover.js'
+
+export default function QueuePage() {
+  const [items, setItems] = useState<Item[] | null>(null)
+  const [error, setError] = useState(false)
+
+  useEffect(() => {
+    void api
+      .listCollection({ ripped: 'not_ripped' })
+      .then((res) => setItems([...res.items].reverse()))
+      .catch(() => setError(true))
+  }, [])
+
+  function markRipped(id: number) {
+    void api
+      .setRip(id, true)
+      .then(() => setItems((list) => (list ?? []).filter((i) => i.id !== id)))
+      .catch(() => setError(true))
+  }
+
+  return (
+    <div className="space-y-3">
+      <p className="text-sm text-neutral-400">Rip queue — oldest additions first.</p>
+      {error && <p className="text-sm text-red-400">Could not load the queue.</p>}
+      {items && items.length === 0 && (
+        <div className="py-12 text-center">
+          <p className="text-neutral-400">Nothing waiting to be ripped.</p>
+          <Link to="/scan" className="mt-2 inline-block text-sm text-emerald-400">
+            Scan something →
+          </Link>
+        </div>
+      )}
+      {items &&
+        items.map((item) => (
+          <div key={item.id} className="flex items-center gap-3 rounded-xl border border-neutral-800 bg-neutral-900 p-3">
+            <Cover src={item.artworkUrl} alt="" className="size-12 shrink-0" />
+            <div className="min-w-0 flex-1">
+              <p className="truncate text-sm font-medium">{item.title}</p>
+              <p className="truncate text-xs text-neutral-400">
+                {item.artist} · added {new Date(item.dateAdded + 'Z').toLocaleDateString()}
+              </p>
+            </div>
+            <button
+              type="button"
+              onClick={() => markRipped(item.id)}
+              className="shrink-0 rounded-lg bg-emerald-500 px-3 py-1.5 text-sm font-medium text-neutral-950"
+            >
+              Mark ripped
+            </button>
+            <Link to={`/item/${item.id}`} className="shrink-0 text-xs text-neutral-400">
+              details
+            </Link>
+          </div>
+        ))}
+    </div>
+  )
+}
+```
+
+`web/src/pages/LibraryPage.tsx` — two edits: header row above the search input:
+```tsx
+      <div className="flex gap-3 text-sm">
+        <Link to="/stats" className="text-emerald-400">
+          Stats
+        </Link>
+        <Link to="/queue" className="text-emerald-400">
+          Queue
+        </Link>
+      </div>
+```
+and a loan chip after the rip chips (RIP row): a third chip group rendered like the others — state `onLoan: boolean`, chip label 'On loan', toggling sets/clears, params include `...(onLoan ? { onLoan: 'true' } : {})`:
+```tsx
+        <button
+          type="button"
+          onClick={() => setOnLoan((v) => !v)}
+          className={`rounded-full px-3 py-1 text-xs font-medium ${
+            onLoan ? 'bg-emerald-500 text-neutral-950' : 'border border-neutral-700 text-neutral-300'
+          }`}
+        >
+          On loan
+        </button>
+```
+(effect deps gain `onLoan`; params builder gains the onLoan spread.)
+
+`web/src/App.tsx` — import QueuePage + route inside the protected block: `<Route path="/queue" element={<QueuePage />} />`.
+
+- [ ] **Step 5: Run tests**
+
+Run: `npx vitest run web/test/library.test.tsx web/test/queue.test.tsx && npm test && npm run typecheck`
+Expected: ALL PASS (182 + 4 new = 186).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A && git commit -m "feat: rip queue page, library stats/queue links and on-loan chip"
+```
+
+---
+
+### Task 13: Stats page
+
+**Files:**
+- Create: `web/src/pages/StatsPage.tsx`
+- Modify: `web/src/App.tsx` (route)
+- Test: `web/test/stats.test.tsx` (new)
+
+- [ ] **Step 1: Write the failing test `web/test/stats.test.tsx`**
+
+```tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import { MemoryRouter } from 'react-router-dom'
+import StatsPage from '../src/pages/StatsPage.js'
+import type { Stats } from '../src/types.js'
+
+vi.mock('../src/api.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/api.js')>()
+  return { ...actual, api: { ...actual.api, getStats: vi.fn() } }
+})
+import { api } from '../src/api.js'
+
+const stats: Stats = {
+  totals: { items: 4, ripped: 1, notRipped: 3, onLoan: 1 },
+  ripRatio: 0.25,
+  formats: [
+    { name: 'CD', count: 3 },
+    { name: 'Vinyl', count: 1 },
+  ],
+  decades: [{ name: '1990s', count: 4 }],
+  topGenres: [
+    { name: 'Electronic', count: 3 },
+    { name: 'Downtempo', count: 2 },
+  ],
+  topArtists: [{ name: 'Massive Attack', count: 2 }],
+  addedByMonth: [
+    { month: '2025-10', count: 0 },
+    { month: '2025-11', count: 0 },
+    { month: '2025-12', count: 0 },
+    { month: '2026-01', count: 0 },
+    { month: '2026-02', count: 0 },
+    { month: '2026-03', count: 0 },
+    { month: '2026-04', count: 0 },
+    { month: '2026-05', count: 0 },
+    { month: '2026-06', count: 0 },
+    { month: '2026-07', count: 0 },
+    { month: '2026-08', count: 4 },
+    { month: '2026-09', count: 0 },
+  ],
+}
+
+beforeEach(() => {
+  vi.mocked(api.getStats).mockReset()
+  vi.mocked(api.getStats).mockResolvedValue(stats as never)
+})
+
+describe('StatsPage', () => {
+  it('renders totals and rip ratio', async () => {
+    render(
+      <MemoryRouter>
+        <StatsPage />
+      </MemoryRouter>
+    )
+    expect(await screen.findByText('4')).toBeTruthy()
+    expect(screen.getByText(/25% ripped/i)).toBeTruthy()
+    expect(screen.getByText(/1 on loan/i)).toBeTruthy()
+  })
+
+  it('renders format, genre, artist and month bars', async () => {
+    render(
+      <MemoryRouter>
+        <StatsPage />
+      </MemoryRouter>
+    )
+    expect(await screen.findByText('CD')).toBeTruthy()
+    expect(screen.getByText('Electronic')).toBeTruthy()
+    expect(screen.getByText('Massive Attack')).toBeTruthy()
+    expect(screen.getByText('1990s')).toBeTruthy()
+    // month bars: 12 bars rendered
+    expect(document.querySelectorAll('[data-bar]').length).toBeGreaterThanOrEqual(12)
+  })
+
+  it('error state on failure', async () => {
+    vi.mocked(api.getStats).mockRejectedValue(new TypeError('fetch failed'))
+    render(
+      <MemoryRouter>
+        <StatsPage />
+      </MemoryRouter>
+    )
+    expect(await screen.findByText(/could not load stats/i)).toBeTruthy()
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run web/test/stats.test.tsx`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Create `web/src/pages/StatsPage.tsx`** — full file:
+
+```tsx
+import { useEffect, useState } from 'react'
+import { api } from '../api.js'
+import type { Stats } from '../types.js'
+
+function Bar({ name, count, max }: { name: string; count: number; max: number }) {
+  return (
+    <div className="flex items-center gap-2 text-sm">
+      <span className="w-28 shrink-0 truncate text-neutral-300">{name}</span>
+      <div className="h-2.5 flex-1 overflow-hidden rounded-full bg-neutral-800">
+        <div className="h-full rounded-full bg-emerald-500" style={{ width: `${max === 0 ? 0 : (count / max) * 100}%` }} />
+      </div>
+      <span className="w-8 shrink-0 text-right text-neutral-500">{count}</span>
+    </div>
+  )
+}
+
+function Card({ value, label }: { value: string | number; label: string }) {
+  return (
+    <div className="rounded-xl border border-neutral-800 bg-neutral-900 p-4 text-center">
+      <p className="text-2xl font-semibold">{value}</p>
+      <p className="text-xs text-neutral-400">{label}</p>
+    </div>
+  )
+}
+
+export default function StatsPage() {
+  const [stats, setStats] = useState<Stats | null>(null)
+  const [error, setError] = useState(false)
+
+  useEffect(() => {
+    void api
+      .getStats()
+      .then(setStats)
+      .catch(() => setError(true))
+  }, [])
+
+  if (error) return <p className="py-8 text-center text-sm text-red-400">Could not load stats.</p>
+  if (!stats) return <p className="py-8 text-center text-sm text-neutral-400">Loading…</p>
+
+  const maxOf = (rows: { count: number }[]) => Math.max(1, ...rows.map((r) => r.count))
+  const maxMonth = Math.max(1, ...stats.addedByMonth.map((m) => m.count))
+  const ratioPct = Math.round(stats.ripRatio * 100)
+
+  return (
+    <div className="space-y-4">
+      <div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+        <Card value={stats.totals.items} label="in collection" />
+        <Card value={stats.totals.ripped} label="ripped" />
+        <Card value={stats.totals.notRipped} label="not ripped" />
+        <Card value={stats.totals.onLoan} label="on loan" />
+      </div>
+
+      <div className="flex items-center gap-4 rounded-xl border border-neutral-800 bg-neutral-900 p-4">
+        <div
+          className="size-20 shrink-0 rounded-full"
+          style={{
+            background: `conic-gradient(#34d399 ${ratioPct}%, #262626 ${ratioPct}% 100%)`,
+          }}
+          role="img"
+          aria-label={`rip ratio ${ratioPct}%`}
+        />
+        <p className="text-sm text-neutral-300">{ratioPct}% ripped</p>
+      </div>
+
+      <section className="space-y-2 rounded-xl border border-neutral-800 bg-neutral-900 p-4">
+        <h2 className="text-sm font-semibold uppercase tracking-wide text-neutral-400">Formats</h2>
+        {stats.formats.length === 0 && <p className="text-sm text-neutral-500">No data yet.</p>}
+        {stats.formats.map((f) => (
+          <Bar key={f.name} name={f.name} count={f.count} max={maxOf(stats.formats)} />
+        ))}
+      </section>
+
+      <section className="space-y-2 rounded-xl border border-neutral-800 bg-neutral-900 p-4">
+        <h2 className="text-sm font-semibold uppercase tracking-wide text-neutral-400">Genres</h2>
+        {stats.topGenres.map((g) => (
+          <Bar key={g.name} name={g.name} count={g.count} max={maxOf(stats.topGenres)} />
+        ))}
+      </section>
+
+      <section className="space-y-2 rounded-xl border border-neutral-800 bg-neutral-900 p-4">
+        <h2 className="text-sm font-semibold uppercase tracking-wide text-neutral-400">Top artists</h2>
+        {stats.topArtists.map((a) => (
+          <Bar key={a.name} name={a.name} count={a.count} max={maxOf(stats.topArtists)} />
+        ))}
+      </section>
+
+      <section className="space-y-2 rounded-xl border border-neutral-800 bg-neutral-900 p-4">
+        <h2 className="text-sm font-semibold uppercase tracking-wide text-neutral-400">Decades</h2>
+        {stats.decades.map((d) => (
+          <Bar key={d.name} name={d.name} count={d.count} max={maxOf(stats.decades)} />
+        ))}
+      </section>
+
+      <section className="space-y-2 rounded-xl border border-neutral-800 bg-neutral-900 p-4">
+        <h2 className="text-sm font-semibold uppercase tracking-wide text-neutral-400">Added per month</h2>
+        <div className="flex h-24 items-end gap-1">
+          {stats.addedByMonth.map((m) => (
+            <div key={m.month} className="flex flex-1 flex-col items-center gap-1" title={`${m.month}: ${m.count}`}>
+              <div
+                data-bar
+                className="w-full rounded-t bg-emerald-500"
+                style={{ height: `${(m.count / maxMonth) * 100}%`, minHeight: m.count > 0 ? '4px' : '1px', background: m.count > 0 ? '#34d399' : '#262626' }}
+              />
+              <span className="text-[10px] text-neutral-500">{m.month.slice(5)}</span>
+            </div>
+          ))}
+        </div>
+      </section>
+    </div>
+  )
+}
+```
+
+- [ ] **Step 4: Register the route in `web/src/App.tsx`** — import StatsPage + `<Route path="/stats" element={<StatsPage />} />` in the protected block.
+
+- [ ] **Step 5: Run tests**
+
+Run: `npx vitest run web/test/stats.test.tsx && npm test && npm run typecheck`
+Expected: ALL PASS (186 + 3 new = 189).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A && git commit -m "feat: stats page with css bar charts and rip-ratio donut"
+```
+
+---
+
+### Task 14: Settings — Data section (export + backups)
+
+**Files:**
+- Modify: `web/src/pages/SettingsPage.tsx`
+- Test: `web/test/settings.test.tsx` (append)
+
+- [ ] **Step 1: Append failing tests to `web/test/settings.test.tsx`**
+
+(Extend the api mock override list with triggerBackup/getBackups. The file's fetch stub pattern for AuthProvider stays.)
+
+```tsx
+  it('data section: export link, backup now, backups list', async () => {
+    vi.mocked(api.triggerBackup).mockResolvedValue({ file: 'record-shop-2026-09-03-120000.db' } as never)
+    vi.mocked(api.getBackups).mockResolvedValue({
+      backups: [{ file: 'record-shop-2026-09-03-120000.db', sizeBytes: 12345, createdAt: '2026-09-03T12:00:00Z' }],
+    } as never)
+    renderSettings()
+    expect(await screen.findByRole('link', { name: /export json/i })).toHaveProperty('href')
+    await userEvent.click(screen.getByRole('button', { name: /back up now/i }))
+    await waitFor(() => expect(api.triggerBackup).toHaveBeenCalled())
+    await waitFor(() => expect(screen.getByText(/record-shop-2026-09-03-120000\.db/)).toBeTruthy())
+  })
+
+  it('backup failure surfaces in the flash banner', async () => {
+    vi.mocked(api.triggerBackup).mockRejectedValue(new TypeError('fetch failed'))
+    renderSettings()
+    await userEvent.click(await screen.findByRole('button', { name: /back up now/i }))
+    await waitFor(() => expect(screen.getByText(/backup failed/i)).toBeTruthy())
+  })
+```
+
+(Use the file's existing link-assertion style if `toHaveProperty` clashes.)
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run web/test/settings.test.tsx`
+Expected: FAIL — no Data section.
+
+- [ ] **Step 3: Implement — add to `web/src/pages/SettingsPage.tsx`** (after the Library sync Section, before Users):
+
+```tsx
+      <Section title="Data">
+        <div className="flex flex-wrap gap-2">
+          <a
+            href={api.exportUrl()}
+            download
+            className="rounded-xl border border-neutral-700 px-3 py-1.5 text-sm text-neutral-300"
+          >
+            Export JSON
+          </a>
+          <button
+            type="button"
+            onClick={() =>
+              void api
+                .triggerBackup()
+                .then(() => api.getBackups())
+                .then((res) => setBackups(res.backups))
+                .then(() => flash('ok', 'Backup created'))
+                .catch(() => flash('error', 'Backup failed'))
+            }
+            className="rounded-xl border border-neutral-700 px-3 py-1.5 text-sm text-neutral-300"
+          >
+            Back up now
+          </button>
+        </div>
+        {backups && backups.length > 0 && (
+          <ul className="space-y-1 text-xs text-neutral-400">
+            {backups.map((b) => (
+              <li key={b.file} className="flex justify-between gap-2">
+                <span className="truncate">{b.file}</span>
+                <span className="shrink-0">
+                  {(b.sizeBytes / 1024).toFixed(0)} KB · {new Date(b.createdAt).toLocaleString()}
+                </span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </Section>
+```
+
+State: `const [backups, setBackups] = useState<BackupFile[] | null>(null)` (+ type import) and load on mount for admins:
+```ts
+  useEffect(() => {
+    if (user?.isAdmin) {
+      void api.getBackups().then((res) => setBackups(res.backups)).catch(() => {})
+    }
+  }, [user])
+```
+(The existing admin listUsers effect can be extended instead of a second effect — implementer's choice, one effect is fine.)
+
+- [ ] **Step 4: Run tests**
+
+Run: `npx vitest run web/test/settings.test.tsx && npm test && npm run typecheck`
+Expected: ALL PASS (189 + 2 new = 191).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A && git commit -m "feat: settings data section with export and backups"
+```
+
+---
+
+### Task 15: Full verification + deploy note
+
+**Files:**
+- Modify: none (verification task)
+
+- [ ] **Step 1: Full suite + typecheck + build**
+
+Run: `npm test && npm run typecheck && npm run build`
+Expected: 191 tests pass (82 backend baseline + 109 across wave-1 backend/frontend), typecheck clean, both dists built.
+
+- [ ] **Step 2: Verify the migration on the deployed instance's data (dry run)**
+
+The deployed instance at `/home/samu/record-shop/data/record-shop.db` has real data (if the user has been using it) and runs the pre-v2 schema. Before restarting it, copy the DB and open the copy:
+
+```bash
+cp data/record-shop.db /tmp/opencode/rs-migrate-test.db
+node -e "
+import Database from 'better-sqlite3';
+import { migrateUpgrades } from './server/dist/db.js';
+const db = new Database('/tmp/opencode/rs-migrate-test.db');
+migrateUpgrades(db);
+console.log('version:', db.prepare(\"SELECT value FROM app_meta WHERE key='schema_version'\").get());
+console.log('cols:', db.prepare('PRAGMA table_info(digital_albums)').all().map(c => c.name).join(','));
+"
+```
+Expected: `version: {value: '2'}` and `last_played_at` present, existing rows intact. Delete the test copy afterwards.
+
+- [ ] **Step 3: Restart the deployed instance**
+
+```bash
+pkill -f "node /home/samu/record-shop/server/dist/index.js"
+sleep 1
+npm run build
+setsid nohup node /home/samu/record-shop/server/dist/index.js > /home/samu/record-shop/data/server.log 2>&1 < /dev/null &
+sleep 2
+curl -s http://localhost:3000/api/health
+curl -s http://localhost:3000/ | grep -o '<title>[^<]*</title>'
+```
+Expected: `{"ok":true}` + SPA title; migration runs on boot against the real data.
+
+- [ ] **Step 4: Manual device checklist additions** (record, do not automate)
+
+- Play an album on the phone (audio codec support, seek, auto-advance)
+- Mini-bar persists across tab navigation
+- Lend/return from the item page
+- Export download on the phone (files app)
+
+- [ ] **Step 5: Commit (if anything changed) or close out**
+
+```bash
+git status --short   # should be clean; the deploy artifacts are gitignored
+```
+
+---
+
+## API additions summary (reference)
+
+| Method | Path | Notes |
+| --- | --- | --- |
+| GET | `/api/stream/:songId` | Range passthrough, 502 `stream_unavailable` |
+| GET | `/api/album/:subsonicId/tracks` | `{album:{id,title,artist}, tracks:[{id,title,duration,track}]}` |
+| POST | `/api/album/:subsonicId/played` | stamps `last_played_at` (404 unknown) |
+| GET | `/api/stats` | totals + ripRatio + formats/decades/genres/artists + addedByMonth |
+| GET | `/api/export` | per-user JSON backup artifact (no secrets) |
+| POST | `/api/backup` | admin; prunes to 7 |
+| GET | `/api/backups` | admin; file list |
+| POST | `/api/collection/:id/loan` | 400 empty borrower, 409 `already_on_loan` |
+| GET | `/api/loans` | `{active, history}` |
+| POST | `/api/loans/:id/return` | 404 when missing/returned |
+| GET | `/api/collection/:id` | + `matchedAlbum`, + `loan` |
+| GET | `/api/collection?onLoan=` | loan-state filter |
+
+**Detail response additions:** `matchedAlbum: {id, subsonicId, lastPlayedAt} | null`, `loan: {id, borrower, lentAt} | null`.