From e376863b573170f45b3f920fea768df5dc01b9de Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 14:49:12 +0800
Subject: [PATCH 01/12] feat: introduce run_search seam + first /api/search
 integration tests (#11)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app.py                   | 31 +++++++++----
 tests/test_search_api.py | 94 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+), 8 deletions(-)
 create mode 100644 tests/test_search_api.py

diff --git a/app.py b/app.py
index ceab462..1b47e92 100644
--- a/app.py
+++ b/app.py
@@ -546,6 +546,28 @@ def _default_runner(cmd):
 run_rip = _default_runner
 
 
+def _default_search_runner(cmd):
+    """Run `rip search` as a subprocess (ADR-0001), returning the finished
+    CompletedProcess (returncode/stdout/stderr). Search is one-shot — it writes
+    its results to a file and exits — so unlike the streaming download runner
+    this blocks and captures output in one go. This is the seam tests replace
+    with a fake so no test ever launches a real `rip search` process."""
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=30,
+    )
+
+
+# Injectable subprocess boundary for Search (mirrors run_rip). Tests swap this
+# for a fake returning a result with the same .returncode/.stdout/.stderr shape;
+# production runs the real `rip search`.
+run_search = _default_search_runner
+
+
 def register_queued(task):
     """Register a submitted Download in server Active state as `queued` and
     announce it immediately, before any worker is free. Guarantees a submitted
@@ -908,14 +930,7 @@ def search_music():
 
         logger.info(f"Executing command: {' '.join(cmd)}")
 
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            timeout=30,
-        )
+        result = run_search(cmd)
 
         logger.info(f"Command completed with return code: {result.returncode}")
 
diff --git a/tests/test_search_api.py b/tests/test_search_api.py
new file mode 100644
index 0000000..8d5ea5b
--- /dev/null
+++ b/tests/test_search_api.py
@@ -0,0 +1,94 @@
+"""Seam: the Search endpoint (/api/search), driven through the Flask test client
+against a fake `rip search` runner.
+
+Search shells out to `rip search --output-file <tmp> ...` (ADR-0001): the real
+runner writes the results JSON to the temp file the endpoint created and returns
+a CompletedProcess. These tests swap run_search for a fake of the same shape, so
+no test ever launches a real `rip` process.
+"""
+import json
+import re
+
+import app as app_module
+
+
+class FakeCompleted:
+    """Same shape as subprocess.CompletedProcess where run_search uses it:
+    .returncode / .stdout / .stderr."""
+
+    def __init__(self, returncode=0, stdout="", stderr=""):
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+
+
+def fake_search_runner(items, returncode=0, stdout="", stderr=""):
+    """Build a fake `rip search` runner: writes the canned results JSON to the
+    --output-file path the endpoint passed on the command line (just as real
+    `rip search` does), then returns a CompletedProcess-shaped result."""
+    def runner(cmd):
+        if returncode == 0:
+            output_path = cmd[cmd.index("--output-file") + 1]
+            with open(output_path, "w") as f:
+                json.dump(items, f)
+        return FakeCompleted(returncode=returncode, stdout=stdout, stderr=stderr)
+    return runner
+
+
+def _search(client, **payload):
+    payload.setdefault("query", "radiohead")
+    payload.setdefault("type", "album")
+    payload.setdefault("source", "qobuz")
+    return client.post("/api/search", json=payload)
+
+
+def test_search_success_returns_parsed_results(client, monkeypatch):
+    items = [
+        {"id": "111", "source": "qobuz", "media_type": "album", "desc": "OK Computer by Radiohead"},
+        {"id": "222", "source": "qobuz", "media_type": "album", "desc": "Kid A by Radiohead"},
+    ]
+    monkeypatch.setattr(app_module, "run_search", fake_search_runner(items))
+
+    resp = _search(client, query="radiohead")
+    assert resp.status_code == 200
+    data = resp.get_json()
+    # Response shape is unchanged: results / query / source / total_count.
+    assert set(["results", "query", "source", "total_count"]).issubset(data.keys())
+    assert data["query"] == "radiohead"
+    assert data["source"] == "qobuz"
+    assert data["total_count"] == 2
+
+    first = data["results"][0]
+    assert first["id"] == "111"
+    assert first["title"] == "OK Computer"
+    assert first["artist"] == "Radiohead"
+    assert first["url"] == "https://open.qobuz.com/album/111"
+
+
+def test_search_nonzero_exit_is_500_error(client, monkeypatch):
+    monkeypatch.setattr(
+        app_module,
+        "run_search",
+        fake_search_runner([], returncode=1, stdout="Traceback (most recent call last):"),
+    )
+
+    resp = _search(client, query="radiohead")
+    assert resp.status_code == 500
+    data = resp.get_json()
+    assert "error" in data
+    assert data["debug_info"]["return_code"] == 1
+
+
+def test_search_missing_query_is_rejected(client):
+    resp = client.post("/api/search", json={"type": "album", "source": "qobuz"})
+    assert resp.status_code == 400
+
+
+def test_search_empty_output_reports_no_results(client, monkeypatch):
+    monkeypatch.setattr(app_module, "run_search", fake_search_runner([]))
+
+    resp = _search(client, query="nothing here")
+    assert resp.status_code == 200
+    data = resp.get_json()
+    assert data["results"] == []
+    assert data["total_count"] == 0

From 38eaaae53fc9e1de41f15264846343678f1be24a Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 14:50:58 +0800
Subject: [PATCH 02/12] feat: extract build_search_command pure function (#12)

Mirror build_rip_command in the Search slice: pull the rip search
argv assembly out of search_music() into a side-effect-free
build_search_command(source, type, query, output_file, config_path).
Config-path inclusion now reuses the same exists-check semantics.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app.py                        | 20 ++++++++++++++++----
 tests/test_command_builder.py | 28 +++++++++++++++++++++++++++-
 2 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/app.py b/app.py
index 1b47e92..9a922ba 100644
--- a/app.py
+++ b/app.py
@@ -503,6 +503,19 @@ def build_rip_command(
     return cmd
 
 
+def build_search_command(source, search_type, query, output_file, *, config_path=None):
+    """Construct the `rip search` argv. Pure (no side effects) so it can be
+    tested directly. Mirrors build_rip_command's config-path handling: the
+    --config-path flag is only added when the config file exists. This is the
+    single place the search invocation is assembled."""
+    cmd = ["rip"]
+    if config_path and os.path.exists(config_path):
+        cmd.extend(["--config-path", config_path])
+    cmd.extend(["search", "--output-file", output_file])
+    cmd.extend([source, search_type, query])
+    return cmd
+
+
 def classify_download(returncode, output):
     """Map a finished `rip` run to a terminal Download state from its exit code
     and stdout. Pure, so the worker's terminal-state logic is unit-testable."""
@@ -918,15 +931,14 @@ def search_music():
 
         logger.info(f"Created temp file: {tmp_path}")
 
-        cmd = ["rip"]
         if os.path.exists(STREAMRIP_CONFIG):
-            cmd.extend(["--config-path", STREAMRIP_CONFIG])
             logger.info(f"Using config file: {STREAMRIP_CONFIG}")
         else:
             logger.warning(f"Config file not found at: {STREAMRIP_CONFIG}")
 
-        cmd.extend(["search", "--output-file", tmp_path])
-        cmd.extend([source, search_type, query])
+        cmd = build_search_command(
+            source, search_type, query, tmp_path, config_path=STREAMRIP_CONFIG
+        )
 
         logger.info(f"Executing command: {' '.join(cmd)}")
 
diff --git a/tests/test_command_builder.py b/tests/test_command_builder.py
index 0f1cb1d..0816692 100644
--- a/tests/test_command_builder.py
+++ b/tests/test_command_builder.py
@@ -1,6 +1,6 @@
 """Seam 2: the rip command builder is a pure function."""
 import app as app_module
-from app import build_rip_command
+from app import build_rip_command, build_search_command
 
 
 def test_command_includes_quality_url_and_download_dir():
@@ -36,3 +36,29 @@ def test_redownload_adds_no_db_flag():
 def test_normal_download_omits_no_db_flag():
     cmd = build_rip_command('https://x/1', 3, download_dir='/m')
     assert '--no-db' not in cmd
+
+
+def test_search_command_orders_source_type_query():
+    cmd = build_search_command('qobuz', 'album', 'daft punk', '/tmp/out.txt')
+    assert cmd[0] == 'rip'
+    assert '--output-file' in cmd
+    assert cmd[cmd.index('--output-file') + 1] == '/tmp/out.txt'
+    assert cmd[-3:] == ['qobuz', 'album', 'daft punk']
+
+
+def test_search_command_omits_config_path_when_missing(tmp_path):
+    missing = str(tmp_path / 'nope.toml')
+    cmd = build_search_command(
+        'tidal', 'track', 'q', '/tmp/o.txt', config_path=missing
+    )
+    assert '--config-path' not in cmd
+
+
+def test_search_command_includes_config_path_when_present(tmp_path):
+    cfg = tmp_path / 'config.toml'
+    cfg.write_text('x = 1')
+    cmd = build_search_command(
+        'tidal', 'track', 'q', '/tmp/o.txt', config_path=str(cfg)
+    )
+    assert '--config-path' in cmd
+    assert cmd[cmd.index('--config-path') + 1] == str(cfg)

From 93ea248e4ac144e7ed864da5125a2e42b46baf24 Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 14:52:38 +0800
Subject: [PATCH 03/12] feat: extract classify_search_error pure function (#13)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app.py                        | 39 +++++++++++++++++++------------
 tests/test_classify_search.py | 43 +++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 15 deletions(-)
 create mode 100644 tests/test_classify_search.py

diff --git a/app.py b/app.py
index 9a922ba..6731f98 100644
--- a/app.py
+++ b/app.py
@@ -529,6 +529,29 @@ def classify_download(returncode, output):
     return "completed"
 
 
+def classify_search_error(returncode, stdout):
+    """Map a finished `rip search` run to a user-facing error message from its
+    exit code and stdout. Pure (mirrors classify_download), so the route's error
+    mapping has locality and a real test surface. Returns None on success."""
+    if returncode == 0:
+        return None
+    error_msg = "Streamrip search failed"
+    if stdout:
+        if "InvalidAppSecretError" in stdout:
+            error_msg = "Invalid Qobuz app secrets. Update your config with valid secrets or run 'rip config --update' in the container."
+        elif "Traceback" in stdout:
+            error_msg = (
+                "Streamrip encountered an error (check logs for full traceback)"
+            )
+        elif "authentication" in stdout.lower():
+            error_msg = (
+                "Authentication failed - check your Qobuz credentials in config"
+            )
+        elif "credentials" in stdout.lower():
+            error_msg = "Invalid credentials - check your Qobuz configuration"
+    return error_msg
+
+
 def _default_runner(cmd):
     """Run `rip` as a subprocess (ADR-0001), yielding stripped stdout lines and
     finally returning the exit code. This is the seam tests replace with a fake
@@ -962,21 +985,7 @@ def search_music():
             logger.error(
                 f"Streamrip command failed with return code {result.returncode}"
             )
-            error_msg = "Streamrip search failed"
-
-            if result.stdout:
-                if "InvalidAppSecretError" in result.stdout:
-                    error_msg = "Invalid Qobuz app secrets. Update your config with valid secrets or run 'rip config --update' in the container."
-                elif "Traceback" in result.stdout:
-                    error_msg = (
-                        "Streamrip encountered an error (check logs for full traceback)"
-                    )
-                elif "authentication" in result.stdout.lower():
-                    error_msg = (
-                        "Authentication failed - check your Qobuz credentials in config"
-                    )
-                elif "credentials" in result.stdout.lower():
-                    error_msg = "Invalid credentials - check your Qobuz configuration"
+            error_msg = classify_search_error(result.returncode, result.stdout)
 
             return jsonify(
                 {
diff --git a/tests/test_classify_search.py b/tests/test_classify_search.py
new file mode 100644
index 0000000..983fa79
--- /dev/null
+++ b/tests/test_classify_search.py
@@ -0,0 +1,43 @@
+"""Classification of a finished `rip search` run to a user-facing error (pure fn)."""
+from app import classify_search_error
+
+
+def test_success_returns_no_error():
+    assert classify_search_error(0, "some results output") is None
+
+
+def test_invalid_app_secret():
+    out = "blah InvalidAppSecretError blah"
+    assert classify_search_error(1, out) == (
+        "Invalid Qobuz app secrets. Update your config with valid secrets or "
+        "run 'rip config --update' in the container."
+    )
+
+
+def test_traceback():
+    out = "Traceback (most recent call last):\n  File ..."
+    assert classify_search_error(1, out) == (
+        "Streamrip encountered an error (check logs for full traceback)"
+    )
+
+
+def test_authentication_failure():
+    out = "Qobuz authentication error"
+    assert classify_search_error(1, out) == (
+        "Authentication failed - check your Qobuz credentials in config"
+    )
+
+
+def test_bad_credentials():
+    out = "bad credentials supplied"
+    assert classify_search_error(1, out) == (
+        "Invalid credentials - check your Qobuz configuration"
+    )
+
+
+def test_generic_fallback_nonzero_unrecognised_stdout():
+    assert classify_search_error(1, "something unexpected") == "Streamrip search failed"
+
+
+def test_generic_fallback_empty_stdout():
+    assert classify_search_error(1, "") == "Streamrip search failed"

From 10ac95c0638bc47c13d328a6614bb807b9ee286a Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 14:55:34 +0800
Subject: [PATCH 04/12] feat: extract parse_search_results pure function (#14)

Move rip search output parsing out of search_music() into a pure
parse_search_results(content, source, search_type). It owns the JSON
decode, the desc -> title/artist split, and the construct_url wiring,
and returns a ParsedSearch(results, error) the endpoint maps to its
response. The endpoint keeps the temp-file lifecycle and logging.

Returns ([], "empty") for blank output and ([], JSONDecodeError) for
malformed JSON without raising. Adds direct unit tests for well-formed,
by-split, missing-fields, empty, and malformed inputs. /api/search
response shape unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app.py                     | 103 +++++++++++++++++++++++--------------
 tests/test_parse_search.py |  91 ++++++++++++++++++++++++++++++++
 2 files changed, 155 insertions(+), 39 deletions(-)
 create mode 100644 tests/test_parse_search.py

diff --git a/app.py b/app.py
index 6731f98..46cb5b6 100644
--- a/app.py
+++ b/app.py
@@ -8,6 +8,7 @@
 import tempfile
 import threading
 import time
+from collections import namedtuple
 
 import requests
 from flask import (
@@ -552,6 +553,59 @@ def classify_search_error(returncode, stdout):
     return error_msg
 
 
+ParsedSearch = namedtuple("ParsedSearch", ["results", "error"])
+
+
+def parse_search_results(content, source, search_type):
+    """Turn the raw text `rip search --output-file` wrote into the result dicts
+    the endpoint serves. Pure (no file IO, no subprocess), so the most
+    correctness-sensitive part of Search — parsing an external program's output —
+    is unit-testable directly rather than only through a live `rip` run.
+
+    Returns a ParsedSearch(results, error):
+      - success      -> (list_of_result_dicts, None)
+      - empty/blank  -> ([], "empty")            # rip wrote nothing
+      - malformed    -> ([], <JSONDecodeError>)  # rip wrote non-JSON
+    Never raises on bad input; the endpoint maps `error` to its response. Owns
+    the `desc` -> title/artist split and the construct_url wiring."""
+    if not content or content.strip() == "":
+        return ParsedSearch([], "empty")
+
+    try:
+        search_data = json.loads(content)
+    except json.JSONDecodeError as e:
+        return ParsedSearch([], e)
+
+    results = []
+    for item in search_data:
+        item_id = item.get("id", "")
+        media_type = item.get("media_type", search_type)
+        url = construct_url(item.get("source", source), media_type, item_id)
+
+        desc = item.get("desc", "")
+        artist = ""
+        title = desc
+        if " by " in desc:
+            parts = desc.rsplit(" by ", 1)
+            title = parts[0]
+            artist = parts[1]
+
+        results.append(
+            {
+                "id": item_id,
+                "service": item.get("source", source),
+                "type": media_type,
+                "artist": artist if artist else desc,
+                "title": title if artist else "",
+                "desc": desc,
+                "url": url,
+                "album_art": "",
+            }
+        )
+
+    return ParsedSearch(results, None)
+
+
 def _default_runner(cmd):
     """Run `rip` as a subprocess (ADR-0001), yielding stripped stdout lines and
     finally returning the exit code. This is the seam tests replace with a fake
@@ -1017,7 +1071,9 @@ def search_music():
                 logger.info(f"File content length: {len(content)} characters")
                 logger.debug(f"File content (first 500 chars):\n{content[:500]}")
 
-                if not content or content.strip() == "":
+                parsed = parse_search_results(content, source, search_type)
+
+                if parsed.error == "empty":
                     logger.warning("Temp file is empty!")
                     return jsonify(
                         {
@@ -1034,44 +1090,8 @@ def search_music():
                         }
                     )
 
-                try:
-                    search_data = json.loads(content)
-                    logger.info(
-                        f"Successfully parsed JSON with {len(search_data)} items"
-                    )
-
-                    for idx, item in enumerate(search_data):
-                        item_id = item.get("id", "")
-                        media_type = item.get("media_type", search_type)
-                        url = construct_url(
-                            item.get("source", source), media_type, item_id
-                        )
-
-                        desc = item.get("desc", "")
-                        artist = ""
-                        title = desc
-
-                        if " by " in desc:
-                            parts = desc.rsplit(" by ", 1)
-                            title = parts[0]
-                            artist = parts[1]
-
-                        result_item = {
-                            "id": item_id,
-                            "service": item.get("source", source),
-                            "type": media_type,
-                            "artist": artist if artist else desc,
-                            "title": title if artist else "",
-                            "desc": desc,
-                            "url": url,
-                            "album_art": "",
-                        }
-                        results.append(result_item)
-
-                        if idx < 3:  # Log first 3 results
-                            logger.debug(f"Result {idx + 1}: {result_item}")
-
-                except json.JSONDecodeError as e:
+                if isinstance(parsed.error, json.JSONDecodeError):
+                    e = parsed.error
                     logger.error("=" * 60)
                     logger.error("JSON PARSE ERROR")
                     logger.error(f"Error: {e}")
@@ -1109,6 +1129,11 @@ def search_music():
                         500,
                     )
 
+                results = parsed.results
+                logger.info(f"Successfully parsed JSON with {len(results)} items")
+                for idx, result_item in enumerate(results[:3]):
+                    logger.debug(f"Result {idx + 1}: {result_item}")
+
         except FileNotFoundError:
             logger.error(f"Temp file not found: {tmp_path}")
             return jsonify(
diff --git a/tests/test_parse_search.py b/tests/test_parse_search.py
new file mode 100644
index 0000000..f6398a1
--- /dev/null
+++ b/tests/test_parse_search.py
@@ -0,0 +1,91 @@
+"""Parsing of `rip search`'s output file into result dicts (pure fn).
+
+parse_search_results is the most correctness-sensitive part of Search: it turns
+the raw text `rip search --output-file` wrote into the dicts /api/search serves.
+Being pure (no file IO, no subprocess) it is tested directly here, not only
+through a live `rip` run.
+"""
+import json
+
+from app import parse_search_results
+
+
+def test_wellformed_results_are_parsed():
+    content = json.dumps(
+        [
+            {"id": "111", "source": "qobuz", "media_type": "album", "desc": "OK Computer by Radiohead"},
+            {"id": "222", "source": "qobuz", "media_type": "album", "desc": "Kid A by Radiohead"},
+        ]
+    )
+    parsed = parse_search_results(content, "qobuz", "album")
+
+    assert parsed.error is None
+    assert len(parsed.results) == 2
+    first = parsed.results[0]
+    assert first["id"] == "111"
+    assert first["service"] == "qobuz"
+    assert first["type"] == "album"
+    assert first["url"] == "https://open.qobuz.com/album/111"
+
+
+def test_desc_title_by_artist_split():
+    content = json.dumps(
+        [{"id": "1", "source": "qobuz", "media_type": "album", "desc": "OK Computer by Radiohead"}]
+    )
+    item = parse_search_results(content, "qobuz", "album").results[0]
+    assert item["title"] == "OK Computer"
+    assert item["artist"] == "Radiohead"
+
+
+def test_desc_without_by_keeps_whole_as_artist():
+    content = json.dumps(
+        [{"id": "1", "source": "qobuz", "media_type": "artist", "desc": "Radiohead"}]
+    )
+    item = parse_search_results(content, "qobuz", "artist").results[0]
+    # No " by " -> whole desc is the artist, title empty (unchanged behaviour).
+    assert item["artist"] == "Radiohead"
+    assert item["title"] == ""
+
+
+def test_rsplit_uses_last_by_separator():
+    content = json.dumps(
+        [{"id": "1", "source": "qobuz", "media_type": "album", "desc": "Day by Day by Someone"}]
+    )
+    item = parse_search_results(content, "qobuz", "album").results[0]
+    assert item["title"] == "Day by Day"
+    assert item["artist"] == "Someone"
+
+
+def test_missing_optional_fields_fall_back():
+    # No id, no source, no media_type, no desc.
+    content = json.dumps([{}])
+    parsed = parse_search_results(content, "tidal", "track")
+
+    assert parsed.error is None
+    item = parsed.results[0]
+    assert item["id"] == ""
+    # source falls back to the request source, media_type to the search type.
+    assert item["service"] == "tidal"
+    assert item["type"] == "track"
+    assert item["desc"] == ""
+    # Empty id -> construct_url returns "".
+    assert item["url"] == ""
+    assert item["album_art"] == ""
+
+
+def test_empty_list_parses_to_no_results():
+    parsed = parse_search_results("[]", "qobuz", "album")
+    assert parsed.error is None
+    assert parsed.results == []
+
+
+def test_empty_content_signals_empty():
+    assert parse_search_results("", "qobuz", "album").error == "empty"
+    assert parse_search_results("   \n ", "qobuz", "album").error == "empty"
+    assert parse_search_results(None, "qobuz", "album").error == "empty"
+
+
+def test_malformed_json_signals_decode_error_without_raising():
+    parsed = parse_search_results("{not json", "qobuz", "album")
+    assert parsed.results == []
+    assert isinstance(parsed.error, json.JSONDecodeError)

From 764e3ad4b8aa24160f07b98805ae8ec24bddc6f2 Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 15:00:48 +0800
Subject: [PATCH 05/12] feat: introduce http_get seam + Source interface,
 proven on Qobuz (#15)

Add an injectable http_get seam (mirroring run_rip / read_audio_tags) and a
Source interface (url / album_art / metadata). Migrate Qobuz fully behind a
QobuzSource adapter: URL construction both directions, art, metadata, and
credential/app_id reading, collapsing the duplicate app_id regex into one
place. The album-art, metadata-extraction, and search paths dispatch to the
adapter for Qobuz; other sources keep their inline code until later slices.
Add unit tests exercising the adapter through a fake http_get with canned JSON
(no network), a route-level album-art test, and a Source glossary entry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CONTEXT.md                  |  13 ++
 app.py                      | 319 +++++++++++++++++++++---------------
 tests/test_album_art_api.py |  71 ++++++++
 tests/test_qobuz_source.py  | 187 +++++++++++++++++++++
 4 files changed, 462 insertions(+), 128 deletions(-)
 create mode 100644 tests/test_album_art_api.py
 create mode 100644 tests/test_qobuz_source.py

diff --git a/CONTEXT.md b/CONTEXT.md
index bc47c0c..72db308 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -67,3 +67,16 @@ tracks that *are* present, which streamrip writes into every file. An album is:
   **Missing disc**.
 - **Unknown** — completeness cannot be determined, because no present track has
   readable tags to reveal the expected total.
+
+### Source
+A single music service (Qobuz, Tidal, Deezer, SoundCloud, ...) and everything
+that is specific to it: how to build a share URL from an id and read an id back
+out of one (**url** / parse, both directions), how to fetch its **album art**,
+and how to read **metadata** from one of its URLs. A Source owns its
+credentials/keys too (Qobuz, for instance, reads its app_id and auth token from
+the **Streamrip database**'s config). Each Source reaches the network only
+through the injectable `http_get` seam, mirroring the `run_rip` and
+`read_audio_tags` seams, so an adapter can be exercised with canned JSON and no
+real network. Sources are migrated behind this single interface one at a time;
+a not-yet-migrated source keeps its quirks inline (e.g. in `construct_url` and
+`extract_metadata_from_url`) until its slice lands.
diff --git a/app.py b/app.py
index 46cb5b6..3fe941b 100644
--- a/app.py
+++ b/app.py
@@ -105,6 +105,18 @@ def first(key):
 read_audio_tags = _default_tag_reader
 
 
+def _default_http_get(url, **kwargs):
+    """Perform an HTTP GET. This is the seam every Source's network access flows
+    through (mirrors run_rip / read_audio_tags); tests swap it for a fake that
+    returns canned JSON so adapters are exercised with no real network."""
+    return requests.get(url, **kwargs)
+
+
+# Injectable HTTP boundary for Source adapters. Tests swap this for a fake whose
+# return value has the real response's .status_code / .json() shape.
+http_get = _default_http_get
+
+
 def _is_audio_file(filename):
     return filename.lower().endswith(AUDIO_EXTENSIONS)
 
@@ -1202,7 +1214,7 @@ def get_album_art():
 
     try:
         if source == "qobuz":
-            result = fetch_single_album_art(item_id, media_type, None)
+            result = qobuz_source.album_art(item_id, media_type)
             album_art_cache[cache_key] = result
             return jsonify(
                 {
@@ -1334,104 +1346,200 @@ def library_album_tracks():
         return jsonify({"error": str(e)}), 500
 
 
-def get_qobuz_credentials():
-    try:
-        if os.path.exists(STREAMRIP_CONFIG):
-            with open(STREAMRIP_CONFIG, "r") as f:
-                config_content = f.read()
+class Source:
+    """A single music source (Qobuz, Tidal, ...), owning everything that source
+    specific: how to build a share URL from an id, how to fetch its album art,
+    and how to read metadata back out of one of its URLs. Adapters reach the
+    network only through the injectable ``http_get`` seam so they are testable
+    with canned JSON. See the *Source* glossary entry in CONTEXT.md.
 
-            app_id = re.search(r'app_id\s*=\s*["\']?([^"\'\n]+)["\']?', config_content)
-            token = re.search(r'password_or_token\s*=\s*"([^"]+)"', config_content)
+    The Source refactor migrates sources behind this interface one at a time;
+    until a source is migrated its quirks stay inline (e.g. in ``construct_url``
+    and ``extract_metadata_from_url``)."""
 
-            return {
-                "app_id": app_id.group(1).strip() if app_id else "950096963",
-                "token": token.group(1).strip() if token else None,
-            }
-    except Exception as e:
-        logger.error(f"Error reading Qobuz credentials: {e}")
-    return {"app_id": "950096963", "token": None}
+    name = None
 
+    def url(self, media_type, item_id):
+        """Build the canonical share URL for ``media_type``/``item_id``."""
+        raise NotImplementedError
 
-def fetch_single_album_art(item_id, media_type, app_id):
-    creds = get_qobuz_credentials()
-    if not creds["token"]:
-        return {}
+    def album_art(self, item_id, media_type):
+        """Fetch album-art (and any cheap extra metadata) for one item. Returns
+        a dict with at least an ``album_art`` key; ``{}`` when unavailable."""
+        raise NotImplementedError
 
-    try:
-        response = requests.get(
-            f"https://www.qobuz.com/api.json/0.2/{media_type}/get",
-            params={
-                "app_id": creds["app_id"],
-                f"{media_type}_id": item_id,
-            },
-            headers={
-                "X-App-Id": creds["app_id"],
-                "X-User-Auth-Token": creds["token"],
-            },
-            timeout=3,
-        )
-        if response.status_code == 200:
-            data = response.json()
-            image = data.get("image", {})
-
-            year = None
-            release_date = data.get("release_date_original", "")
-            if release_date:
-                year = release_date[:4]
-
-            return {
-                "album_art": image.get("large")
-                or image.get("small")
-                or image.get("thumbnail")
-                or "",
-                "tracks_count": data.get("tracks_count"),
-                "release_type": data.get("release_type"),
-                "year": year,
-            }
-    except Exception as e:
-        logger.error(f"Error fetching Qobuz album art: {e}")
-    return {}
+    def metadata(self, url):
+        """Read whatever metadata this source exposes for one of its URLs.
+        Returns a partial dict to merge onto the base metadata shape."""
+        raise NotImplementedError
 
 
-def get_qobuz_app_id():
-    try:
+# Single place the Qobuz app_id is read out of the streamrip config. Both the
+# bare app_id and the full credentials reads share this regex (collapsing the
+# duplicate that used to live in get_qobuz_credentials and get_qobuz_app_id).
+_QOBUZ_APP_ID_RE = r'app_id\s*=\s*["\']?([^"\'\n]+)["\']?'
+_QOBUZ_FALLBACK_APP_ID = "950096963"
+
+
+class QobuzSource(Source):
+    """Qobuz adapter — the richest source: it needs credentials and hits the
+    real Qobuz API for both art and metadata. Owns Qobuz URL construction (both
+    directions), art, metadata, and credential/app_id reading from the streamrip
+    config. All network access goes through the module-level ``http_get`` seam."""
+
+    name = "qobuz"
+    api_base = "https://www.qobuz.com/api.json/0.2"
+    _url_patterns = {
+        "album": "https://open.qobuz.com/album/{id}",
+        "track": "https://open.qobuz.com/track/{id}",
+        "artist": "https://open.qobuz.com/artist/{id}",
+        "playlist": "https://open.qobuz.com/playlist/{id}",
+    }
+    _id_re = r"/(album|track|playlist|artist)/([0-9]+)"
+
+    def _read_config(self):
         if os.path.exists(STREAMRIP_CONFIG):
             with open(STREAMRIP_CONFIG, "r") as f:
-                config_content = f.read()
-                # logger.debug(f"Config file content: {config_content[:200]}...")  # First 200 chars
+                return f.read()
+        return ""
 
-            app_id_match = re.search(
-                r'app_id\s*=\s*["\']?([^"\'\n]+)["\']?', config_content
+    def credentials(self):
+        """Read the Qobuz app_id and auth token from the streamrip config,
+        falling back to a known-working app_id and no token."""
+        try:
+            config_content = self._read_config()
+            if config_content:
+                app_id = re.search(_QOBUZ_APP_ID_RE, config_content)
+                token = re.search(
+                    r'password_or_token\s*=\s*"([^"]+)"', config_content
+                )
+                return {
+                    "app_id": app_id.group(1).strip()
+                    if app_id
+                    else _QOBUZ_FALLBACK_APP_ID,
+                    "token": token.group(1).strip() if token else None,
+                }
+        except Exception as e:
+            logger.error(f"Error reading Qobuz credentials: {e}")
+        return {"app_id": _QOBUZ_FALLBACK_APP_ID, "token": None}
+
+    def app_id(self):
+        """The Qobuz app_id alone (metadata calls need no token)."""
+        return self.credentials()["app_id"]
+
+    def url(self, media_type, item_id):
+        if not item_id:
+            return ""
+        pattern = self._url_patterns.get(media_type)
+        if pattern:
+            return pattern.format(id=item_id)
+        return f"https://open.qobuz.com/{media_type}/{item_id}"
+
+    def parse_url(self, url):
+        """Pull (media_type, id) out of a Qobuz URL, or (None, None)."""
+        match = re.search(self._id_re, url)
+        if match:
+            return match.group(1), match.group(2)
+        return None, None
+
+    def album_art(self, item_id, media_type):
+        creds = self.credentials()
+        if not creds["token"]:
+            return {}
+        try:
+            response = http_get(
+                f"{self.api_base}/{media_type}/get",
+                params={
+                    "app_id": creds["app_id"],
+                    f"{media_type}_id": item_id,
+                },
+                headers={
+                    "X-App-Id": creds["app_id"],
+                    "X-User-Auth-Token": creds["token"],
+                },
+                timeout=3,
             )
+            if response.status_code == 200:
+                data = response.json()
+                image = data.get("image", {})
+
+                year = None
+                release_date = data.get("release_date_original", "")
+                if release_date:
+                    year = release_date[:4]
+
+                return {
+                    "album_art": image.get("large")
+                    or image.get("small")
+                    or image.get("thumbnail")
+                    or "",
+                    "tracks_count": data.get("tracks_count"),
+                    "release_type": data.get("release_type"),
+                    "year": year,
+                }
+        except Exception as e:
+            logger.error(f"Error fetching Qobuz album art: {e}")
+        return {}
 
-            if app_id_match:
-                app_id = app_id_match.group(1).strip()
-                logger.debug(f"Found app_id in config: {app_id}")
-                return app_id
-            else:
-                logger.debug("No app_id found in config, using fallback")
+    def metadata(self, url):
+        media_type, item_id = self.parse_url(url)
+        if not item_id:
+            return {}
 
-        # Return a known working app_id as fallback
-        fallback_app_id = "950096963"
-        logger.debug(f"Using fallback app_id: {fallback_app_id}")
-        return fallback_app_id
+        result = {}
+        try:
+            app_id = self.app_id()
+            if media_type == "album":
+                response = http_get(
+                    f"{self.api_base}/album/get",
+                    params={"album_id": item_id, "app_id": app_id},
+                    timeout=5,
+                )
+                if response.status_code == 200:
+                    data = response.json()
+                    result["title"] = data.get("title", "")
+                    result["artist"] = data.get("artist", {}).get("name", "")
+                    if "image" in data:
+                        for size in ["small", "medium", "large", "thumbnail"]:
+                            if size in data["image"]:
+                                result["album_art"] = data["image"][size]
+                                break
+
+            elif media_type == "track":
+                response = http_get(
+                    f"{self.api_base}/track/get",
+                    params={"track_id": item_id, "app_id": app_id},
+                    timeout=5,
+                )
+                if response.status_code == 200:
+                    data = response.json()
+                    result["title"] = data.get("title", "")
+                    result["artist"] = data.get("performer", {}).get("name", "")
+                    album = data.get("album", {})
+                    if "image" in album:
+                        for size in ["small", "medium", "large", "thumbnail"]:
+                            if size in album["image"]:
+                                result["album_art"] = album["image"][size]
+                                break
+        except Exception as e:
+            logger.error(f"Error fetching Qobuz metadata: {e}")
 
-    except Exception as e:
-        logger.error(f"Error extracting app_id: {e}")
-        return "950096963"
+        return result
+
+
+qobuz_source = QobuzSource()
 
 
 def construct_url(source, media_type, item_id):
     if not item_id:
         return ""
 
+    # Migrated sources own their URL construction behind the Source interface;
+    # the rest stay inline until their slice lands.
+    if source == "qobuz":
+        return qobuz_source.url(media_type, item_id)
+
     url_patterns = {
-        "qobuz": {
-            "album": f"https://open.qobuz.com/album/{item_id}",
-            "track": f"https://open.qobuz.com/track/{item_id}",
-            "artist": f"https://open.qobuz.com/artist/{item_id}",
-            "playlist": f"https://open.qobuz.com/playlist/{item_id}",
-        },
         "tidal": {
             "album": f"https://tidal.com/browse/album/{item_id}",
             "track": f"https://tidal.com/browse/track/{item_id}",
@@ -1478,11 +1586,11 @@ def extract_metadata_from_url(url):
 
         elif "qobuz.com" in url:
             metadata["service"] = "qobuz"
-            match = re.search(r"/(album|track|playlist|artist)/([0-9]+)", url)
-            if match:
-                metadata["type"] = match.group(1)
-                metadata["id"] = match.group(2)
-                metadata.update(fetch_qobuz_metadata(metadata["id"], metadata["type"]))
+            media_type, item_id = qobuz_source.parse_url(url)
+            if item_id:
+                metadata["type"] = media_type
+                metadata["id"] = item_id
+                metadata.update(qobuz_source.metadata(url))
 
         elif "tidal.com" in url:
             metadata["service"] = "tidal"
@@ -1508,51 +1616,6 @@ def extract_metadata_from_url(url):
     return metadata
 
 
-def fetch_qobuz_metadata(item_id, item_type):
-    metadata = {}
-    try:
-        app_id = get_qobuz_app_id()
-        api_base = "https://www.qobuz.com/api.json/0.2"
-
-        if item_type == "album":
-            response = requests.get(
-                f"{api_base}/album/get",
-                params={"album_id": item_id, "app_id": app_id},
-                timeout=5,
-            )
-            if response.status_code == 200:
-                data = response.json()
-                metadata["title"] = data.get("title", "")
-                metadata["artist"] = data.get("artist", {}).get("name", "")
-                if "image" in data:
-                    for size in ["small", "medium", "large", "thumbnail"]:
-                        if size in data["image"]:
-                            metadata["album_art"] = data["image"][size]
-                            break
-
-        elif item_type == "track":
-            response = requests.get(
-                f"{api_base}/track/get",
-                params={"track_id": item_id, "app_id": app_id},
-                timeout=5,
-            )
-            if response.status_code == 200:
-                data = response.json()
-                metadata["title"] = data.get("title", "")
-                metadata["artist"] = data.get("performer", {}).get("name", "")
-                album = data.get("album", {})
-                if "image" in album:
-                    for size in ["small", "medium", "large", "thumbnail"]:
-                        if size in album["image"]:
-                            metadata["album_art"] = album["image"][size]
-                            break
-
-    except Exception as e:
-        logger.error(f"Error fetching Qobuz metadata: {e}")
-
-    return metadata
-
-
 def fetch_deezer_metadata(item_id, item_type):
     metadata = {}
     try:
diff --git a/tests/test_album_art_api.py b/tests/test_album_art_api.py
new file mode 100644
index 0000000..8ab06a2
--- /dev/null
+++ b/tests/test_album_art_api.py
@@ -0,0 +1,71 @@
+"""Seam: the /api/album-art endpoint for Qobuz, driven through the Flask test
+client against a fake http_get (issue #15).
+
+Proves the route dispatches Qobuz art to the Qobuz Source adapter and that the
+externally observable response shape is unchanged, with no real network call.
+"""
+import app as app_module
+
+
+class FakeResponse:
+    def __init__(self, payload, status_code=200):
+        self._payload = payload
+        self.status_code = status_code
+
+    def json(self):
+        return self._payload
+
+
+def _stub_http_get(monkeypatch, payload, status_code=200):
+    calls = []
+
+    def _get(url, **kwargs):
+        calls.append({"url": url, **kwargs})
+        return FakeResponse(payload, status_code)
+
+    monkeypatch.setattr(app_module, "http_get", _get)
+    return calls
+
+
+def _stub_config(monkeypatch, tmp_path, content):
+    cfg = tmp_path / "config.toml"
+    cfg.write_text(content)
+    monkeypatch.setattr(app_module, "STREAMRIP_CONFIG", str(cfg))
+
+
+def test_album_art_qobuz_uses_adapter(client, monkeypatch, tmp_path):
+    app_module.album_art_cache.clear()
+    _stub_config(monkeypatch, tmp_path, 'app_id = "id1"\npassword_or_token = "tok"\n')
+    calls = _stub_http_get(
+        monkeypatch,
+        {
+            "image": {"large": "http://art/large.jpg"},
+            "tracks_count": 9,
+            "release_type": "album",
+            "release_date_original": "1997-05-21",
+        },
+    )
+
+    resp = client.get(
+        "/api/album-art", query_string={"source": "qobuz", "type": "album", "id": "111"}
+    )
+    assert resp.status_code == 200
+    data = resp.get_json()
+    assert data["album_art"] == "http://art/large.jpg"
+    assert data["tracks_count"] == 9
+    assert data["release_type"] == "album"
+    assert data["year"] == "1997"
+    # Hit the adapter's seam, not the real network.
+    assert calls and calls[0]["url"] == "https://www.qobuz.com/api.json/0.2/album/get"
+
+
+def test_album_art_qobuz_caches_result(client, monkeypatch, tmp_path):
+    app_module.album_art_cache.clear()
+    _stub_config(monkeypatch, tmp_path, 'app_id = "id1"\npassword_or_token = "tok"\n')
+    calls = _stub_http_get(monkeypatch, {"image": {"large": "http://art/x.jpg"}})
+
+    q = {"source": "qobuz", "type": "album", "id": "222"}
+    client.get("/api/album-art", query_string=q)
+    client.get("/api/album-art", query_string=q)
+    # Second call served from cache -> seam hit exactly once.
+    assert len(calls) == 1
diff --git a/tests/test_qobuz_source.py b/tests/test_qobuz_source.py
new file mode 100644
index 0000000..94fb269
--- /dev/null
+++ b/tests/test_qobuz_source.py
@@ -0,0 +1,187 @@
+"""Unit tests for the Qobuz Source adapter (issue #15).
+
+The adapter owns Qobuz URL construction (both directions), album-art, metadata,
+and credential/app_id reading. Network access flows through the injectable
+``http_get`` seam, which these tests swap for a fake returning canned JSON so the
+adapter is exercised with no real network. Credential reading is driven by a
+fake streamrip config on disk via the STREAMRIP_CONFIG seam.
+"""
+import app as app_module
+from app import QobuzSource
+
+
+class FakeResponse:
+    """Mimics the slice of requests.Response the adapter uses."""
+
+    def __init__(self, payload, status_code=200):
+        self._payload = payload
+        self.status_code = status_code
+
+    def json(self):
+        return self._payload
+
+
+def fake_http_get(payload, status_code=200):
+    """Build a fake http_get that records its calls and returns canned JSON."""
+    calls = []
+
+    def _get(url, **kwargs):
+        calls.append({"url": url, **kwargs})
+        return FakeResponse(payload, status_code)
+
+    _get.calls = calls
+    return _get
+
+
+# --- url() : id -> URL (one direction) -------------------------------------
+
+def test_url_known_media_types():
+    src = QobuzSource()
+    assert src.url("album", "111") == "https://open.qobuz.com/album/111"
+    assert src.url("track", "222") == "https://open.qobuz.com/track/222"
+    assert src.url("artist", "333") == "https://open.qobuz.com/artist/333"
+    assert src.url("playlist", "444") == "https://open.qobuz.com/playlist/444"
+
+
+def test_url_empty_id_is_blank():
+    assert QobuzSource().url("album", "") == ""
+
+
+def test_url_unknown_media_type_falls_back():
+    assert QobuzSource().url("label", "9") == "https://open.qobuz.com/label/9"
+
+
+# --- parse_url() : URL -> id (other direction) -----------------------------
+
+def test_parse_url_extracts_type_and_id():
+    src = QobuzSource()
+    assert src.parse_url("https://open.qobuz.com/album/111") == ("album", "111")
+    assert src.parse_url("https://www.qobuz.com/track/222") == ("track", "222")
+
+
+def test_parse_url_no_match_is_none():
+    assert QobuzSource().parse_url("https://qobuz.com/") == (None, None)
+
+
+# --- credentials() / app_id() : config reading (single regex) --------------
+
+def _write_config(monkeypatch, tmp_path, content):
+    cfg = tmp_path / "config.toml"
+    cfg.write_text(content)
+    monkeypatch.setattr(app_module, "STREAMRIP_CONFIG", str(cfg))
+
+
+def test_credentials_read_from_config(monkeypatch, tmp_path):
+    _write_config(
+        monkeypatch,
+        tmp_path,
+        'app_id = "123456"\npassword_or_token = "secret-token"\n',
+    )
+    creds = QobuzSource().credentials()
+    assert creds == {"app_id": "123456", "token": "secret-token"}
+
+
+def test_app_id_uses_same_read(monkeypatch, tmp_path):
+    _write_config(monkeypatch, tmp_path, 'app_id = "987654"\n')
+    src = QobuzSource()
+    assert src.app_id() == "987654"
+    # No token in config -> credentials still resolve, token None.
+    assert src.credentials()["token"] is None
+
+
+def test_credentials_fall_back_when_config_missing(monkeypatch, tmp_path):
+    monkeypatch.setattr(
+        app_module, "STREAMRIP_CONFIG", str(tmp_path / "does-not-exist.toml")
+    )
+    creds = QobuzSource().credentials()
+    assert creds["app_id"] == "950096963"
+    assert creds["token"] is None
+
+
+# --- album_art() through the fake seam -------------------------------------
+
+def test_album_art_fetches_through_http_get(monkeypatch, tmp_path):
+    _write_config(monkeypatch, tmp_path, 'app_id = "id1"\npassword_or_token = "tok"\n')
+    fake = fake_http_get(
+        {
+            "image": {"large": "http://art/large.jpg", "small": "http://art/small.jpg"},
+            "tracks_count": 12,
+            "release_type": "album",
+            "release_date_original": "2001-06-05",
+        }
+    )
+    monkeypatch.setattr(app_module, "http_get", fake)
+
+    result = QobuzSource().album_art("111", "album")
+    assert result["album_art"] == "http://art/large.jpg"
+    assert result["tracks_count"] == 12
+    assert result["release_type"] == "album"
+    assert result["year"] == "2001"
+    # The seam was hit with the album endpoint and id, no real network.
+    assert len(fake.calls) == 1
+    call = fake.calls[0]
+    assert call["url"] == "https://www.qobuz.com/api.json/0.2/album/get"
+    assert call["params"]["album_id"] == "111"
+    assert call["headers"]["X-User-Auth-Token"] == "tok"
+
+
+def test_album_art_without_token_returns_empty(monkeypatch, tmp_path):
+    _write_config(monkeypatch, tmp_path, 'app_id = "id1"\n')  # no token
+    fake = fake_http_get({"image": {"large": "x"}})
+    monkeypatch.setattr(app_module, "http_get", fake)
+
+    assert QobuzSource().album_art("111", "album") == {}
+    # No token -> never reaches the network.
+    assert fake.calls == []
+
+
+def test_album_art_non_200_is_empty(monkeypatch, tmp_path):
+    _write_config(monkeypatch, tmp_path, 'app_id = "id1"\npassword_or_token = "tok"\n')
+    monkeypatch.setattr(app_module, "http_get", fake_http_get({}, status_code=401))
+    assert QobuzSource().album_art("111", "album") == {}
+
+
+# --- metadata() through the fake seam --------------------------------------
+
+def test_album_metadata_through_http_get(monkeypatch, tmp_path):
+    _write_config(monkeypatch, tmp_path, 'app_id = "id1"\n')
+    fake = fake_http_get(
+        {
+            "title": "OK Computer",
+            "artist": {"name": "Radiohead"},
+            "image": {"medium": "http://art/medium.jpg"},
+        }
+    )
+    monkeypatch.setattr(app_module, "http_get", fake)
+
+    meta = QobuzSource().metadata("https://open.qobuz.com/album/111")
+    assert meta["title"] == "OK Computer"
+    assert meta["artist"] == "Radiohead"
+    assert meta["album_art"] == "http://art/medium.jpg"
+    assert fake.calls[0]["params"]["album_id"] == "111"
+
+
+def test_track_metadata_through_http_get(monkeypatch, tmp_path):
+    _write_config(monkeypatch, tmp_path, 'app_id = "id1"\n')
+    fake = fake_http_get(
+        {
+            "title": "Paranoid Android",
+            "performer": {"name": "Radiohead"},
+            "album": {"image": {"small": "http://art/small.jpg"}},
+        }
+    )
+    monkeypatch.setattr(app_module, "http_get", fake)
+
+    meta = QobuzSource().metadata("https://open.qobuz.com/track/222")
+    assert meta["title"] == "Paranoid Android"
+    assert meta["artist"] == "Radiohead"
+    assert meta["album_art"] == "http://art/small.jpg"
+    assert fake.calls[0]["url"] == "https://www.qobuz.com/api.json/0.2/track/get"
+    assert fake.calls[0]["params"]["track_id"] == "222"
+
+
+def test_metadata_unparseable_url_skips_network(monkeypatch):
+    fake = fake_http_get({})
+    monkeypatch.setattr(app_module, "http_get", fake)
+    assert QobuzSource().metadata("https://qobuz.com/no-id-here") == {}
+    assert fake.calls == []

From 32386da0cb6bf0af9807f3f121ba3a403dc41afa Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 15:03:36 +0800
Subject: [PATCH 06/12] feat: Deezer adapter behind the Source interface (#16)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a DeezerSource adapter mirroring QobuzSource (#15): URL construction both
directions, art, and metadata, all reaching the network only through the shared
http_get seam. Deezer's art is asymmetric — album/track art is a pure URL
template (no HTTP), while artist art is a real Deezer API call via http_get.
Move Deezer metadata fetch into the adapter (dropping the inline
fetch_deezer_metadata + its requests.get) and dispatch the album-art,
construct_url, and metadata-extraction paths to it for Deezer URLs. Add unit
tests covering artist-API vs album/track-template art and metadata through a
fake http_get, plus route-level album-art tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app.py                      | 151 ++++++++++++++++++++++--------------
 tests/test_album_art_api.py |  26 +++++++
 tests/test_deezer_source.py | 151 ++++++++++++++++++++++++++++++++++++
 3 files changed, 269 insertions(+), 59 deletions(-)
 create mode 100644 tests/test_deezer_source.py

diff --git a/app.py b/app.py
index 3fe941b..3443dbf 100644
--- a/app.py
+++ b/app.py
@@ -1237,26 +1237,11 @@ def get_album_art():
             return jsonify({"album_art": ""})
 
         elif source == "deezer":
-            if media_type == "artist":
-                try:
-                    response = requests.get(
-                        f"https://api.deezer.com/artist/{item_id}", timeout=3
-                    )
-                    if response.status_code == 200:
-                        data = response.json()
-                        album_art = data.get("picture_medium", data.get("picture", ""))
-                        if album_art:
-                            album_art_cache[cache_key] = album_art
-                            return jsonify({"album_art": album_art})
-                except:
-                    pass
-                return jsonify({"album_art": ""})
-            else:
-                album_art = f"https://api.deezer.com/{media_type}/{item_id}/image"
-                if album_art:
-                    album_art_cache[cache_key] = album_art
-                    return jsonify({"album_art": album_art})
-                return jsonify({"album_art": ""})
+            result = deezer_source.album_art(item_id, media_type)
+            album_art = result.get("album_art", "")
+            if album_art:
+                album_art_cache[cache_key] = album_art
+            return jsonify({"album_art": album_art})
 
         elif source == "soundcloud":
             # SoundCloud doesn't provide easy access to artwork
@@ -1530,6 +1515,86 @@ def metadata(self, url):
 qobuz_source = QobuzSource()
 
 
+class DeezerSource(Source):
+    """Deezer adapter. Deezer needs no credentials. Its art behaviour is
+    asymmetric: album and track art are pure URL templates served by Deezer's
+    image endpoint (no HTTP from us), while **artist** art has no such template
+    and must be read from a real Deezer API call through the ``http_get`` seam.
+    Metadata for album/track URLs also flows through ``http_get``."""
+
+    name = "deezer"
+    api_base = "https://api.deezer.com"
+    _url_patterns = {
+        "album": "https://www.deezer.com/album/{id}",
+        "track": "https://www.deezer.com/track/{id}",
+        "artist": "https://www.deezer.com/artist/{id}",
+        "playlist": "https://www.deezer.com/playlist/{id}",
+    }
+    _id_re = r"/(album|track|playlist|artist)/([0-9]+)"
+
+    def url(self, media_type, item_id):
+        if not item_id:
+            return ""
+        pattern = self._url_patterns.get(media_type)
+        if pattern:
+            return pattern.format(id=item_id)
+        return f"https://www.deezer.com/{media_type}/{item_id}"
+
+    def parse_url(self, url):
+        """Pull (media_type, id) out of a Deezer URL, or (None, None)."""
+        match = re.search(self._id_re, url)
+        if match:
+            return match.group(1), match.group(2)
+        return None, None
+
+    def album_art(self, item_id, media_type):
+        # Album/track art is a pure template against Deezer's image endpoint —
+        # no HTTP from us. Only artist art requires a real API call.
+        if media_type != "artist":
+            return {"album_art": f"{self.api_base}/{media_type}/{item_id}/image"}
+        try:
+            response = http_get(f"{self.api_base}/artist/{item_id}", timeout=3)
+            if response.status_code == 200:
+                data = response.json()
+                album_art = data.get("picture_medium", data.get("picture", ""))
+                if album_art:
+                    return {"album_art": album_art}
+        except Exception as e:
+            logger.error(f"Error fetching Deezer artist art: {e}")
+        return {}
+
+    def metadata(self, url):
+        media_type, item_id = self.parse_url(url)
+        if not item_id:
+            return {}
+
+        result = {}
+        try:
+            if media_type == "album":
+                response = http_get(f"{self.api_base}/album/{item_id}", timeout=5)
+                if response.status_code == 200:
+                    data = response.json()
+                    result["title"] = data.get("title", "")
+                    result["artist"] = data.get("artist", {}).get("name", "")
+                    result["album_art"] = data.get("cover_medium", "")
+
+            elif media_type == "track":
+                response = http_get(f"{self.api_base}/track/{item_id}", timeout=5)
+                if response.status_code == 200:
+                    data = response.json()
+                    result["title"] = data.get("title", "")
+                    result["artist"] = data.get("artist", {}).get("name", "")
+                    album = data.get("album", {})
+                    result["album_art"] = album.get("cover_medium", "")
+        except Exception as e:
+            logger.error(f"Error fetching Deezer metadata: {e}")
+
+        return result
+
+
+deezer_source = DeezerSource()
+
+
 def construct_url(source, media_type, item_id):
     if not item_id:
         return ""
@@ -1538,6 +1603,8 @@ def construct_url(source, media_type, item_id):
     # the rest stay inline until their slice lands.
     if source == "qobuz":
         return qobuz_source.url(media_type, item_id)
+    if source == "deezer":
+        return deezer_source.url(media_type, item_id)
 
     url_patterns = {
         "tidal": {
@@ -1546,12 +1613,6 @@ def construct_url(source, media_type, item_id):
             "artist": f"https://tidal.com/browse/artist/{item_id}",
             "playlist": f"https://tidal.com/browse/playlist/{item_id}",
         },
-        "deezer": {
-            "album": f"https://www.deezer.com/album/{item_id}",
-            "track": f"https://www.deezer.com/track/{item_id}",
-            "artist": f"https://www.deezer.com/artist/{item_id}",
-            "playlist": f"https://www.deezer.com/playlist/{item_id}",
-        },
         "soundcloud": {
             "track": f"https://soundcloud.com/{item_id}",
             "album": f"https://soundcloud.com/{item_id}",
@@ -1604,11 +1665,11 @@ def extract_metadata_from_url(url):
 
         elif "deezer.com" in url:
             metadata["service"] = "deezer"
-            match = re.search(r"/(album|track|playlist|artist)/([0-9]+)", url)
-            if match:
-                metadata["type"] = match.group(1)
-                metadata["id"] = match.group(2)
-                metadata.update(fetch_deezer_metadata(metadata["id"], metadata["type"]))
+            media_type, item_id = deezer_source.parse_url(url)
+            if item_id:
+                metadata["type"] = media_type
+                metadata["id"] = item_id
+                metadata.update(deezer_source.metadata(url))
 
     except Exception as e:
         logger.error(f"Error extracting metadata from URL: {e}")
@@ -1616,34 +1677,6 @@ def extract_metadata_from_url(url):
     return metadata
 
 
-def fetch_deezer_metadata(item_id, item_type):
-    metadata = {}
-    try:
-        api_base = "https://api.deezer.com"
-
-        if item_type == "album":
-            response = requests.get(f"{api_base}/album/{item_id}", timeout=5)
-            if response.status_code == 200:
-                data = response.json()
-                metadata["title"] = data.get("title", "")
-                metadata["artist"] = data.get("artist", {}).get("name", "")
-                metadata["album_art"] = data.get("cover_medium", "")
-
-        elif item_type == "track":
-            response = requests.get(f"{api_base}/track/{item_id}", timeout=5)
-            if response.status_code == 200:
-                data = response.json()
-                metadata["title"] = data.get("title", "")
-                metadata["artist"] = data.get("artist", {}).get("name", "")
-                album = data.get("album", {})
-                metadata["album_art"] = album.get("cover_medium", "")
-
-    except Exception as e:
-        logger.error(f"Error fetching Deezer metadata: {e}")
-
-    return metadata
-
-
 @app.route("/api/download-from-url", methods=["POST"])
 def download_from_url():
     data = request.json
diff --git a/tests/test_album_art_api.py b/tests/test_album_art_api.py
index 8ab06a2..35ba6de 100644
--- a/tests/test_album_art_api.py
+++ b/tests/test_album_art_api.py
@@ -69,3 +69,29 @@ def test_album_art_qobuz_caches_result(client, monkeypatch, tmp_path):
     client.get("/api/album-art", query_string=q)
     # Second call served from cache -> seam hit exactly once.
     assert len(calls) == 1
+
+
+def test_album_art_deezer_album_uses_template_no_network(client, monkeypatch):
+    app_module.album_art_cache.clear()
+    calls = _stub_http_get(monkeypatch, {})
+    resp = client.get(
+        "/api/album-art",
+        query_string={"source": "deezer", "type": "album", "id": "111"},
+    )
+    assert resp.status_code == 200
+    assert resp.get_json()["album_art"] == "https://api.deezer.com/album/111/image"
+    # Album art is a pure template -> no network call.
+    assert calls == []
+
+
+def test_album_art_deezer_artist_uses_api(client, monkeypatch):
+    app_module.album_art_cache.clear()
+    calls = _stub_http_get(monkeypatch, {"picture_medium": "http://art/medium.jpg"})
+    resp = client.get(
+        "/api/album-art",
+        query_string={"source": "deezer", "type": "artist", "id": "333"},
+    )
+    assert resp.status_code == 200
+    assert resp.get_json()["album_art"] == "http://art/medium.jpg"
+    # Artist art hit the adapter's seam, not the real network.
+    assert calls and calls[0]["url"] == "https://api.deezer.com/artist/333"
diff --git a/tests/test_deezer_source.py b/tests/test_deezer_source.py
new file mode 100644
index 0000000..016d797
--- /dev/null
+++ b/tests/test_deezer_source.py
@@ -0,0 +1,151 @@
+"""Unit tests for the Deezer Source adapter (issue #16).
+
+The adapter owns Deezer URL construction (both directions), album-art, and
+metadata. Deezer needs no credentials. Its art is asymmetric: album/track art
+is a pure URL template (no HTTP), while artist art is a real API call through
+the injectable ``http_get`` seam, which these tests swap for a fake returning
+canned JSON so the adapter is exercised with no real network.
+"""
+import app as app_module
+from app import DeezerSource
+
+
+class FakeResponse:
+    """Mimics the slice of requests.Response the adapter uses."""
+
+    def __init__(self, payload, status_code=200):
+        self._payload = payload
+        self.status_code = status_code
+
+    def json(self):
+        return self._payload
+
+
+def fake_http_get(payload, status_code=200):
+    """Build a fake http_get that records its calls and returns canned JSON."""
+    calls = []
+
+    def _get(url, **kwargs):
+        calls.append({"url": url, **kwargs})
+        return FakeResponse(payload, status_code)
+
+    _get.calls = calls
+    return _get
+
+
+# --- url() : id -> URL (one direction) -------------------------------------
+
+def test_url_known_media_types():
+    src = DeezerSource()
+    assert src.url("album", "111") == "https://www.deezer.com/album/111"
+    assert src.url("track", "222") == "https://www.deezer.com/track/222"
+    assert src.url("artist", "333") == "https://www.deezer.com/artist/333"
+    assert src.url("playlist", "444") == "https://www.deezer.com/playlist/444"
+
+
+def test_url_empty_id_is_blank():
+    assert DeezerSource().url("album", "") == ""
+
+
+def test_url_unknown_media_type_falls_back():
+    assert DeezerSource().url("label", "9") == "https://www.deezer.com/label/9"
+
+
+# --- parse_url() : URL -> id (other direction) -----------------------------
+
+def test_parse_url_extracts_type_and_id():
+    src = DeezerSource()
+    assert src.parse_url("https://www.deezer.com/album/111") == ("album", "111")
+    assert src.parse_url("https://deezer.com/track/222") == ("track", "222")
+
+
+def test_parse_url_no_match_is_none():
+    assert DeezerSource().parse_url("https://www.deezer.com/") == (None, None)
+
+
+# --- album_art() : album/track use template (no HTTP) ----------------------
+
+def test_album_art_album_is_template_no_network(monkeypatch):
+    fake = fake_http_get({})
+    monkeypatch.setattr(app_module, "http_get", fake)
+    result = DeezerSource().album_art("111", "album")
+    assert result == {"album_art": "https://api.deezer.com/album/111/image"}
+    # Template art never reaches the network.
+    assert fake.calls == []
+
+
+def test_album_art_track_is_template_no_network(monkeypatch):
+    fake = fake_http_get({})
+    monkeypatch.setattr(app_module, "http_get", fake)
+    result = DeezerSource().album_art("222", "track")
+    assert result == {"album_art": "https://api.deezer.com/track/222/image"}
+    assert fake.calls == []
+
+
+# --- album_art() : artist uses the API via http_get ------------------------
+
+def test_album_art_artist_uses_api(monkeypatch):
+    fake = fake_http_get(
+        {"picture_medium": "http://art/medium.jpg", "picture": "http://art/x.jpg"}
+    )
+    monkeypatch.setattr(app_module, "http_get", fake)
+    result = DeezerSource().album_art("333", "artist")
+    assert result == {"album_art": "http://art/medium.jpg"}
+    assert len(fake.calls) == 1
+    assert fake.calls[0]["url"] == "https://api.deezer.com/artist/333"
+
+
+def test_album_art_artist_falls_back_to_picture(monkeypatch):
+    fake = fake_http_get({"picture": "http://art/x.jpg"})
+    monkeypatch.setattr(app_module, "http_get", fake)
+    assert DeezerSource().album_art("333", "artist") == {
+        "album_art": "http://art/x.jpg"
+    }
+
+
+def test_album_art_artist_non_200_is_empty(monkeypatch):
+    monkeypatch.setattr(app_module, "http_get", fake_http_get({}, status_code=404))
+    assert DeezerSource().album_art("333", "artist") == {}
+
+
+# --- metadata() through the fake seam --------------------------------------
+
+def test_album_metadata_through_http_get(monkeypatch):
+    fake = fake_http_get(
+        {
+            "title": "Discovery",
+            "artist": {"name": "Daft Punk"},
+            "cover_medium": "http://art/medium.jpg",
+        }
+    )
+    monkeypatch.setattr(app_module, "http_get", fake)
+
+    meta = DeezerSource().metadata("https://www.deezer.com/album/111")
+    assert meta["title"] == "Discovery"
+    assert meta["artist"] == "Daft Punk"
+    assert meta["album_art"] == "http://art/medium.jpg"
+    assert fake.calls[0]["url"] == "https://api.deezer.com/album/111"
+
+
+def test_track_metadata_through_http_get(monkeypatch):
+    fake = fake_http_get(
+        {
+            "title": "One More Time",
+            "artist": {"name": "Daft Punk"},
+            "album": {"cover_medium": "http://art/small.jpg"},
+        }
+    )
+    monkeypatch.setattr(app_module, "http_get", fake)
+
+    meta = DeezerSource().metadata("https://www.deezer.com/track/222")
+    assert meta["title"] == "One More Time"
+    assert meta["artist"] == "Daft Punk"
+    assert meta["album_art"] == "http://art/small.jpg"
+    assert fake.calls[0]["url"] == "https://api.deezer.com/track/222"
+
+
+def test_metadata_unparseable_url_skips_network(monkeypatch):
+    fake = fake_http_get({})
+    monkeypatch.setattr(app_module, "http_get", fake)
+    assert DeezerSource().metadata("https://www.deezer.com/no-id-here") == {}
+    assert fake.calls == []

From f066bbb5ed96b3a9778dadbe3213034bfb03ac69 Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 15:10:34 +0800
Subject: [PATCH 07/12] feat: Tidal/SoundCloud/Spotify Source adapters; retire
 construct_url and per-source branches (#17)

Add TidalSource (template url/art, art-only metadata), SoundCloudSource
(empty art, owns the id-mangling), and SpotifySource (no-op metadata, no
art) behind the existing Source interface. Introduce a SOURCES registry
plus resolve_source/GenericSource so URL construction, album-art, and
metadata extraction dispatch over adapters instead of per-source if/elif
chains; construct_url is removed. Qobuz/Deezer gain a domain attr for the
URL->source map. Unit tests cover each new adapter (incl. SoundCloud
id-mangling) and the registry dispatch.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app.py                                  | 285 ++++++++++++++++--------
 tests/test_album_art_api.py             |  42 ++++
 tests/test_extract_metadata_dispatch.py |  66 ++++++
 tests/test_parse_search.py              |   2 +-
 tests/test_soundcloud_source.py         |  49 ++++
 tests/test_spotify_source.py            |  52 +++++
 tests/test_tidal_source.py              |  80 +++++++
 7 files changed, 478 insertions(+), 98 deletions(-)
 create mode 100644 tests/test_extract_metadata_dispatch.py
 create mode 100644 tests/test_soundcloud_source.py
 create mode 100644 tests/test_spotify_source.py
 create mode 100644 tests/test_tidal_source.py

diff --git a/app.py b/app.py
index 3443dbf..42223b5 100644
--- a/app.py
+++ b/app.py
@@ -579,7 +579,7 @@ def parse_search_results(content, source, search_type):
       - empty/blank  -> ([], "empty")            # rip wrote nothing
       - malformed    -> ([], <JSONDecodeError>)  # rip wrote non-JSON
     Never raises on bad input; the endpoint maps `error` to its response. Owns
-    the `desc` -> title/artist split and the construct_url wiring."""
+    the `desc` -> title/artist split and the Source URL wiring."""
     if not content or content.strip() == "":
         return ParsedSearch([], "empty")
 
@@ -592,7 +592,7 @@ def parse_search_results(content, source, search_type):
     for item in search_data:
         item_id = item.get("id", "")
         media_type = item.get("media_type", search_type)
-        url = construct_url(item.get("source", source), media_type, item_id)
+        url = resolve_source(item.get("source", source)).url(media_type, item_id)
 
         desc = item.get("desc", "")
         artist = ""
@@ -1196,14 +1196,12 @@ def get_album_art():
     if not all([source, media_type, item_id]):
         return jsonify({"error": "Missing parameters"}), 400
 
-    # Todo: handle SoundCloud special case and get correct albums if possible
-    if source == "soundcloud":
-        if "|" in item_id:
-            item_id = item_id.split("|")[0]
-        elif "soundcloud:tracks:" in item_id:
-            match = re.search(r"soundcloud:tracks:(\d+)", item_id)
-            if match:
-                item_id = match.group(1)
+    adapter = resolve_source(source)
+
+    # Sources whose ids arrive mangled (SoundCloud) recover the bare id; the
+    # default is identity. Normalising before the cache key keeps caching keyed
+    # on the real id.
+    item_id = adapter.normalize_id(item_id)
 
     cache_key = f"{source}_{media_type}_{item_id}"
     if cache_key in album_art_cache:
@@ -1213,43 +1211,24 @@ def get_album_art():
         return jsonify({"album_art": cached})
 
     try:
+        result = adapter.album_art(item_id, media_type)
+        album_art = result.get("album_art", "")
+        # Qobuz carries extra fields the frontend reads; preserve its richer
+        # cached shape, while every other source caches the bare art string and
+        # only when non-empty (matching prior per-source behaviour).
         if source == "qobuz":
-            result = qobuz_source.album_art(item_id, media_type)
             album_art_cache[cache_key] = result
             return jsonify(
                 {
-                    "album_art": result.get("album_art", ""),
+                    "album_art": album_art,
                     "tracks_count": result.get("tracks_count"),
                     "release_type": result.get("release_type"),
                     "year": result.get("year"),
                 }
             )
-
-        elif source == "tidal":
-            if media_type == "artist":
-                album_art = f"https://resources.tidal.com/images/{item_id}/750x750.jpg"
-            else:
-                album_art = f"https://resources.tidal.com/images/{item_id}/320x320.jpg"
-
-            if album_art:
-                album_art_cache[cache_key] = album_art
-                return jsonify({"album_art": album_art})
-            return jsonify({"album_art": ""})
-
-        elif source == "deezer":
-            result = deezer_source.album_art(item_id, media_type)
-            album_art = result.get("album_art", "")
-            if album_art:
-                album_art_cache[cache_key] = album_art
-            return jsonify({"album_art": album_art})
-
-        elif source == "soundcloud":
-            # SoundCloud doesn't provide easy access to artwork
-            # Just return empty and let the frontend handle placeholders
-            return jsonify({"album_art": ""})
-
-        # Default return for unknown sources
-        return jsonify({"album_art": ""})
+        if album_art:
+            album_art_cache[cache_key] = album_art
+        return jsonify({"album_art": album_art})
 
     except Exception as e:
         logger.error(
@@ -1338,12 +1317,18 @@ class Source:
     network only through the injectable ``http_get`` seam so they are testable
     with canned JSON. See the *Source* glossary entry in CONTEXT.md.
 
-    The Source refactor migrates sources behind this interface one at a time;
-    until a source is migrated its quirks stay inline (e.g. in ``construct_url``
-    and ``extract_metadata_from_url``)."""
+    Every source is now behind this interface; URL construction and metadata
+    extraction dispatch over the ``SOURCES`` registry (via ``resolve_source``)
+    rather than per-source branching."""
 
     name = None
 
+    def normalize_id(self, item_id):
+        """Recover the canonical id from whatever form search hands us. The
+        default is identity; sources whose ids arrive mangled (SoundCloud)
+        override this."""
+        return item_id
+
     def url(self, media_type, item_id):
         """Build the canonical share URL for ``media_type``/``item_id``."""
         raise NotImplementedError
@@ -1373,6 +1358,7 @@ class QobuzSource(Source):
     config. All network access goes through the module-level ``http_get`` seam."""
 
     name = "qobuz"
+    domain = "qobuz.com"
     api_base = "https://www.qobuz.com/api.json/0.2"
     _url_patterns = {
         "album": "https://open.qobuz.com/album/{id}",
@@ -1523,6 +1509,7 @@ class DeezerSource(Source):
     Metadata for album/track URLs also flows through ``http_get``."""
 
     name = "deezer"
+    domain = "deezer.com"
     api_base = "https://api.deezer.com"
     _url_patterns = {
         "album": "https://www.deezer.com/album/{id}",
@@ -1595,35 +1582,163 @@ def metadata(self, url):
 deezer_source = DeezerSource()
 
 
-def construct_url(source, media_type, item_id):
-    if not item_id:
-        return ""
+class TidalSource(Source):
+    """Tidal adapter. Both ``url`` and ``album_art`` are pure URL templates — no
+    HTTP from us — and ``metadata`` only yields the art URL plus the id/type read
+    out of the URL (Tidal exposes no cheap title/artist without an API call)."""
 
-    # Migrated sources own their URL construction behind the Source interface;
-    # the rest stay inline until their slice lands.
-    if source == "qobuz":
-        return qobuz_source.url(media_type, item_id)
-    if source == "deezer":
-        return deezer_source.url(media_type, item_id)
-
-    url_patterns = {
-        "tidal": {
-            "album": f"https://tidal.com/browse/album/{item_id}",
-            "track": f"https://tidal.com/browse/track/{item_id}",
-            "artist": f"https://tidal.com/browse/artist/{item_id}",
-            "playlist": f"https://tidal.com/browse/playlist/{item_id}",
-        },
-        "soundcloud": {
-            "track": f"https://soundcloud.com/{item_id}",
-            "album": f"https://soundcloud.com/{item_id}",
-            "playlist": f"https://soundcloud.com/{item_id}",
-        },
+    name = "tidal"
+    domain = "tidal.com"
+    _url_patterns = {
+        "album": "https://tidal.com/browse/album/{id}",
+        "track": "https://tidal.com/browse/track/{id}",
+        "artist": "https://tidal.com/browse/artist/{id}",
+        "playlist": "https://tidal.com/browse/playlist/{id}",
     }
+    _id_re = r"/(album|track|playlist|artist)/([0-9]+)"
+
+    def url(self, media_type, item_id):
+        if not item_id:
+            return ""
+        pattern = self._url_patterns.get(media_type)
+        if pattern:
+            return pattern.format(id=item_id)
+        return f"https://tidal.com/browse/{media_type}/{item_id}"
+
+    def parse_url(self, url):
+        """Pull (media_type, id) out of a Tidal URL, or (None, None)."""
+        match = re.search(self._id_re, url)
+        if match:
+            return match.group(1), match.group(2)
+        return None, None
+
+    def album_art(self, item_id, media_type):
+        # Pure template against Tidal's image CDN — artist art is larger.
+        size = "750x750" if media_type == "artist" else "320x320"
+        return {
+            "album_art": f"https://resources.tidal.com/images/{item_id}/{size}.jpg"
+        }
+
+    def metadata(self, url):
+        media_type, item_id = self.parse_url(url)
+        if not item_id:
+            return {}
+        return {
+            "album_art": f"https://resources.tidal.com/images/{item_id}/320x320.jpg"
+        }
+
+
+tidal_source = TidalSource()
+
+
+class SoundCloudSource(Source):
+    """SoundCloud adapter. Art is always empty (no easy artwork access) and there
+    is no metadata fetch. SoundCloud ids arrive mangled from search — either as
+    ``id|...`` or as a ``soundcloud:tracks:<n>`` urn — so the adapter owns
+    ``normalize_id`` to recover the bare id. SoundCloud has no album/artist
+    search."""
+
+    name = "soundcloud"
+    _track_urn_re = r"soundcloud:tracks:(\d+)"
+
+    def normalize_id(self, item_id):
+        """Recover the bare SoundCloud id from the mangled forms search emits."""
+        if not item_id:
+            return item_id
+        if "|" in item_id:
+            return item_id.split("|")[0]
+        match = re.search(self._track_urn_re, item_id)
+        if match:
+            return match.group(1)
+        return item_id
+
+    def url(self, media_type, item_id):
+        if not item_id:
+            return ""
+        return f"https://soundcloud.com/{item_id}"
+
+    def album_art(self, item_id, media_type):
+        return {"album_art": ""}
+
+
+soundcloud_source = SoundCloudSource()
+
+
+class SpotifySource(Source):
+    """Spotify adapter. Spotify needs OAuth to read anything, so ``metadata``
+    only records the id/type parsed from the URL and there is no art."""
+
+    name = "spotify"
+    domain = "spotify.com"
+    _id_re = r"/(album|track|playlist|artist)/([a-zA-Z0-9]+)"
+
+    def url(self, media_type, item_id):
+        if not item_id:
+            return ""
+        return f"https://open.spotify.com/{media_type}/{item_id}"
+
+    def parse_url(self, url):
+        """Pull (media_type, id) out of a Spotify URL, or (None, None)."""
+        match = re.search(self._id_re, url)
+        if match:
+            return match.group(1), match.group(2)
+        return None, None
+
+    def album_art(self, item_id, media_type):
+        return {"album_art": ""}
 
-    if source in url_patterns and media_type in url_patterns[source]:
-        return url_patterns[source][media_type]
+    def metadata(self, url):
+        # OAuth required to fetch — record nothing beyond what the caller parses.
+        return {}
+
+
+spotify_source = SpotifySource()
+
+
+class GenericSource(Source):
+    """Fallback for any source without a dedicated adapter. URL is the generic
+    ``open.<source>.com`` template; no art and no metadata. Lets the registry
+    dispatch over a single interface for every source instead of branching on
+    unknown names."""
+
+    def __init__(self, name):
+        self.name = name
+
+    def url(self, media_type, item_id):
+        if not item_id:
+            return ""
+        return f"https://open.{self.name}.com/{media_type}/{item_id}"
+
+    def album_art(self, item_id, media_type):
+        return {"album_art": ""}
+
+
+# Registry of Source adapters, keyed by name. Dispatch over this replaces the
+# old per-source ``construct_url`` / ``extract_metadata_from_url`` branching;
+# ``resolve_source`` hands back a GenericSource for any unregistered name so the
+# interface is uniform. ``SOURCES_BY_DOMAIN`` resolves a pasted URL back to its
+# source for metadata extraction (only sources that parse a URL belong here —
+# SoundCloud has no metadata fetch).
+SOURCES = {
+    src.name: src
+    for src in (
+        qobuz_source,
+        deezer_source,
+        tidal_source,
+        soundcloud_source,
+        spotify_source,
+    )
+}
+SOURCES_BY_DOMAIN = {
+    src.domain: src
+    for src in SOURCES.values()
+    if getattr(src, "domain", None)
+}
 
-    return f"https://open.{source}.com/{media_type}/{item_id}"
+
+def resolve_source(name):
+    """The Source adapter for ``name``, or a GenericSource fallback."""
+    return SOURCES.get(name) or GenericSource(name)
 
 
 def extract_metadata_from_url(url):
@@ -1637,40 +1752,16 @@ def extract_metadata_from_url(url):
     }
 
     try:
-        if "spotify.com" in url:
-            metadata["service"] = "spotify"
-            match = re.search(r"/(album|track|playlist|artist)/([a-zA-Z0-9]+)", url)
-            if match:
-                metadata["type"] = match.group(1)
-                metadata["id"] = match.group(2)
-                # Note: Spotify requires OAuth for metadata, so we can't easily fetch it
-
-        elif "qobuz.com" in url:
-            metadata["service"] = "qobuz"
-            media_type, item_id = qobuz_source.parse_url(url)
-            if item_id:
-                metadata["type"] = media_type
-                metadata["id"] = item_id
-                metadata.update(qobuz_source.metadata(url))
-
-        elif "tidal.com" in url:
-            metadata["service"] = "tidal"
-            match = re.search(r"/(album|track|playlist|artist)/([0-9]+)", url)
-            if match:
-                metadata["type"] = match.group(1)
-                metadata["id"] = match.group(2)
-                metadata["album_art"] = (
-                    f"https://resources.tidal.com/images/{metadata['id']}/320x320.jpg"
-                )
-
-        elif "deezer.com" in url:
-            metadata["service"] = "deezer"
-            media_type, item_id = deezer_source.parse_url(url)
+        adapter = next(
+            (src for dom, src in SOURCES_BY_DOMAIN.items() if dom in url), None
+        )
+        if adapter:
+            metadata["service"] = adapter.name
+            media_type, item_id = adapter.parse_url(url)
             if item_id:
                 metadata["type"] = media_type
                 metadata["id"] = item_id
-                metadata.update(deezer_source.metadata(url))
-
+                metadata.update(adapter.metadata(url))
     except Exception as e:
         logger.error(f"Error extracting metadata from URL: {e}")
 
diff --git a/tests/test_album_art_api.py b/tests/test_album_art_api.py
index 35ba6de..2d2da60 100644
--- a/tests/test_album_art_api.py
+++ b/tests/test_album_art_api.py
@@ -95,3 +95,45 @@ def test_album_art_deezer_artist_uses_api(client, monkeypatch):
     assert resp.get_json()["album_art"] == "http://art/medium.jpg"
     # Artist art hit the adapter's seam, not the real network.
     assert calls and calls[0]["url"] == "https://api.deezer.com/artist/333"
+
+
+def test_album_art_tidal_uses_template_no_network(client, monkeypatch):
+    app_module.album_art_cache.clear()
+    calls = _stub_http_get(monkeypatch, {})
+    resp = client.get(
+        "/api/album-art",
+        query_string={"source": "tidal", "type": "album", "id": "111"},
+    )
+    assert resp.status_code == 200
+    assert (
+        resp.get_json()["album_art"]
+        == "https://resources.tidal.com/images/111/320x320.jpg"
+    )
+    assert calls == []
+
+
+def test_album_art_soundcloud_is_empty(client, monkeypatch):
+    app_module.album_art_cache.clear()
+    calls = _stub_http_get(monkeypatch, {})
+    resp = client.get(
+        "/api/album-art",
+        query_string={"source": "soundcloud", "type": "track", "id": "123"},
+    )
+    assert resp.status_code == 200
+    assert resp.get_json()["album_art"] == ""
+    assert calls == []
+
+
+def test_album_art_soundcloud_id_mangling_feeds_cache_key(client, monkeypatch):
+    # The route normalises the mangled id before keying the cache, so a later
+    # lookup with the bare id hits the same entry. SoundCloud art is empty, so
+    # we observe normalisation through the cache key rather than the art value.
+    app_module.album_art_cache.clear()
+    _stub_http_get(monkeypatch, {})
+    client.get(
+        "/api/album-art",
+        query_string={"source": "soundcloud", "type": "track", "id": "soundcloud:tracks:987"},
+    )
+    # Empty art is never cached; what matters is the route did not crash on the
+    # mangled urn and the adapter recovered the bare id.
+    assert app_module.SoundCloudSource().normalize_id("soundcloud:tracks:987") == "987"
diff --git a/tests/test_extract_metadata_dispatch.py b/tests/test_extract_metadata_dispatch.py
new file mode 100644
index 0000000..2028ddf
--- /dev/null
+++ b/tests/test_extract_metadata_dispatch.py
@@ -0,0 +1,66 @@
+"""extract_metadata_from_url now dispatches over the Source registry by domain
+instead of a per-source if/elif chain (issue #17). These cover the no-HTTP
+sources whose adapters landed in this slice.
+"""
+import app as app_module
+from app import extract_metadata_from_url
+
+
+def _no_network(monkeypatch):
+    def _get(url, **kwargs):
+        raise AssertionError("metadata extraction must not reach the network here")
+
+    monkeypatch.setattr(app_module, "http_get", _get)
+
+
+def test_tidal_url_records_id_type_and_art(monkeypatch):
+    _no_network(monkeypatch)
+    meta = extract_metadata_from_url("https://tidal.com/browse/album/111")
+    assert meta["service"] == "tidal"
+    assert meta["type"] == "album"
+    assert meta["id"] == "111"
+    assert meta["album_art"] == "https://resources.tidal.com/images/111/320x320.jpg"
+
+
+def test_spotify_url_records_only_id_and_type(monkeypatch):
+    _no_network(monkeypatch)
+    meta = extract_metadata_from_url("https://open.spotify.com/track/abc123")
+    assert meta["service"] == "spotify"
+    assert meta["type"] == "track"
+    assert meta["id"] == "abc123"
+    # OAuth required -> no title/artist/art fetched.
+    assert meta["title"] is None
+    assert meta["album_art"] is None
+
+
+def test_unknown_domain_is_all_none(monkeypatch):
+    _no_network(monkeypatch)
+    meta = extract_metadata_from_url("https://example.com/whatever")
+    assert meta["service"] is None
+    assert meta["id"] is None
+
+
+class _FakeResponse:
+    def __init__(self, payload, status_code=200):
+        self._payload = payload
+        self.status_code = status_code
+
+    def json(self):
+        return self._payload
+
+
+def test_deezer_url_still_dispatches_through_seam(monkeypatch):
+    # Guards the registry's domain map: deezer must resolve from its URL and
+    # fetch through the http_get seam.
+    def _get(url, **kwargs):
+        return _FakeResponse(
+            {"title": "Discovery", "artist": {"name": "Daft Punk"},
+             "cover_medium": "http://art.jpg"}
+        )
+
+    monkeypatch.setattr(app_module, "http_get", _get)
+    meta = extract_metadata_from_url("https://www.deezer.com/album/111")
+    assert meta["service"] == "deezer"
+    assert meta["type"] == "album"
+    assert meta["id"] == "111"
+    assert meta["title"] == "Discovery"
diff --git a/tests/test_parse_search.py b/tests/test_parse_search.py
index f6398a1..339aa76 100644
--- a/tests/test_parse_search.py
+++ b/tests/test_parse_search.py
@@ -68,7 +68,7 @@ def test_missing_optional_fields_fall_back():
     assert item["service"] == "tidal"
     assert item["type"] == "track"
     assert item["desc"] == ""
-    # Empty id -> construct_url returns "".
+    # Empty id -> Source.url returns "".
     assert item["url"] == ""
     assert item["album_art"] == ""
 
diff --git a/tests/test_soundcloud_source.py b/tests/test_soundcloud_source.py
new file mode 100644
index 0000000..e6619b0
--- /dev/null
+++ b/tests/test_soundcloud_source.py
@@ -0,0 +1,49 @@
+"""Unit tests for the SoundCloud Source adapter (issue #17).
+
+SoundCloud art is always empty and there is no metadata fetch. The adapter owns
+the id-mangling that used to live in the album-art endpoint: a ``id|...`` split
+and a ``soundcloud:tracks:<n>`` urn extraction.
+"""
+from app import SoundCloudSource
+
+
+# --- normalize_id() : the carried-over id-mangling -------------------------
+
+def test_normalize_id_splits_on_pipe():
+    assert SoundCloudSource().normalize_id("123456|extra|stuff") == "123456"
+
+
+def test_normalize_id_extracts_track_urn():
+    assert SoundCloudSource().normalize_id("soundcloud:tracks:987654") == "987654"
+
+
+def test_normalize_id_pipe_takes_precedence_over_urn():
+    # A pipe is handled first, matching the original endpoint's if/elif order.
+    assert SoundCloudSource().normalize_id("abc|soundcloud:tracks:1") == "abc"
+
+
+def test_normalize_id_plain_id_unchanged():
+    assert SoundCloudSource().normalize_id("plain-id") == "plain-id"
+
+
+def test_normalize_id_empty_unchanged():
+    assert SoundCloudSource().normalize_id("") == ""
+
+
+# --- url() : id -> URL -----------------------------------------------------
+
+def test_url_uses_path_id():
+    assert SoundCloudSource().url("track", "user/song") == (
+        "https://soundcloud.com/user/song"
+    )
+
+
+def test_url_empty_id_is_blank():
+    assert SoundCloudSource().url("track", "") == ""
+
+
+# --- album_art() : always empty --------------------------------------------
+
+def test_album_art_is_always_empty():
+    assert SoundCloudSource().album_art("123", "track") == {"album_art": ""}
+    assert SoundCloudSource().album_art("123", "artist") == {"album_art": ""}
diff --git a/tests/test_spotify_source.py b/tests/test_spotify_source.py
new file mode 100644
index 0000000..12ab35c
--- /dev/null
+++ b/tests/test_spotify_source.py
@@ -0,0 +1,52 @@
+"""Unit tests for the Spotify Source adapter (issue #17).
+
+Spotify needs OAuth to read anything, so ``metadata`` is a no-op (the caller
+records the id/type it parses) and there is no art.
+"""
+import app as app_module
+from app import SpotifySource
+
+
+def _no_network(monkeypatch):
+    def _get(url, **kwargs):
+        raise AssertionError("Spotify adapter must not reach the network")
+
+    monkeypatch.setattr(app_module, "http_get", _get)
+
+
+# --- url() : id -> URL -----------------------------------------------------
+
+def test_url_known_media_types():
+    src = SpotifySource()
+    assert src.url("album", "abc123") == "https://open.spotify.com/album/abc123"
+    assert src.url("track", "def456") == "https://open.spotify.com/track/def456"
+
+
+def test_url_empty_id_is_blank():
+    assert SpotifySource().url("album", "") == ""
+
+
+# --- parse_url() : URL -> id (alphanumeric ids) ----------------------------
+
+def test_parse_url_extracts_alphanumeric_id():
+    src = SpotifySource()
+    assert src.parse_url("https://open.spotify.com/album/6aBxqD") == (
+        "album",
+        "6aBxqD",
+    )
+
+
+def test_parse_url_no_match_is_none():
+    assert SpotifySource().parse_url("https://open.spotify.com/") == (None, None)
+
+
+# --- album_art() / metadata() : no fetch -----------------------------------
+
+def test_album_art_is_empty(monkeypatch):
+    _no_network(monkeypatch)
+    assert SpotifySource().album_art("abc", "album") == {"album_art": ""}
+
+
+def test_metadata_is_noop(monkeypatch):
+    _no_network(monkeypatch)
+    assert SpotifySource().metadata("https://open.spotify.com/album/abc") == {}
diff --git a/tests/test_tidal_source.py b/tests/test_tidal_source.py
new file mode 100644
index 0000000..1feb586
--- /dev/null
+++ b/tests/test_tidal_source.py
@@ -0,0 +1,80 @@
+"""Unit tests for the Tidal Source adapter (issue #17).
+
+Tidal is template-only: ``url`` and ``album_art`` are pure URL templates with no
+HTTP, and ``metadata`` yields the art URL plus the id/type read out of the URL.
+"""
+import app as app_module
+from app import TidalSource
+
+
+def _no_network(monkeypatch):
+    """Swap http_get for a recorder that fails the test if any source touches it."""
+    calls = []
+
+    def _get(url, **kwargs):
+        calls.append(url)
+        raise AssertionError("Tidal adapter must not reach the network")
+
+    monkeypatch.setattr(app_module, "http_get", _get)
+    return calls
+
+
+# --- url() : id -> URL -----------------------------------------------------
+
+def test_url_known_media_types():
+    src = TidalSource()
+    assert src.url("album", "111") == "https://tidal.com/browse/album/111"
+    assert src.url("track", "222") == "https://tidal.com/browse/track/222"
+    assert src.url("artist", "333") == "https://tidal.com/browse/artist/333"
+    assert src.url("playlist", "444") == "https://tidal.com/browse/playlist/444"
+
+
+def test_url_empty_id_is_blank():
+    assert TidalSource().url("album", "") == ""
+
+
+def test_url_unknown_media_type_falls_back():
+    assert TidalSource().url("mix", "9") == "https://tidal.com/browse/mix/9"
+
+
+# --- parse_url() : URL -> id -----------------------------------------------
+
+def test_parse_url_extracts_type_and_id():
+    src = TidalSource()
+    assert src.parse_url("https://tidal.com/browse/album/111") == ("album", "111")
+    assert src.parse_url("https://tidal.com/track/222") == ("track", "222")
+
+
+def test_parse_url_no_match_is_none():
+    assert TidalSource().parse_url("https://tidal.com/") == (None, None)
+
+
+# --- album_art() : pure template, no HTTP ----------------------------------
+
+def test_album_art_non_artist_is_320_template(monkeypatch):
+    _no_network(monkeypatch)
+    assert TidalSource().album_art("111", "album") == {
+        "album_art": "https://resources.tidal.com/images/111/320x320.jpg"
+    }
+
+
+def test_album_art_artist_is_750_template(monkeypatch):
+    _no_network(monkeypatch)
+    assert TidalSource().album_art("333", "artist") == {
+        "album_art": "https://resources.tidal.com/images/333/750x750.jpg"
+    }
+
+
+# --- metadata() : art URL + parsed id, no HTTP -----------------------------
+
+def test_metadata_yields_art_from_parsed_id(monkeypatch):
+    _no_network(monkeypatch)
+    meta = TidalSource().metadata("https://tidal.com/browse/album/111")
+    assert meta == {
+        "album_art": "https://resources.tidal.com/images/111/320x320.jpg"
+    }
+
+
+def test_metadata_unparseable_url_is_empty(monkeypatch):
+    _no_network(monkeypatch)
+    assert TidalSource().metadata("https://tidal.com/no-id-here") == {}

From 2b35e50f07bb41b6f74b30a9d6f7be206fac3300 Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 15:13:44 +0800
Subject: [PATCH 08/12] feat: extract DownloadStore owning Active/History state
 and locks (#18)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move active_downloads, download_history, and their two locks behind a
single DownloadStore class (ADR-0002 seam). All five former call sites —
register, worker, finalize, status, redownload — go through the store via
add_queued / mark_downloading / finalize / snapshot / find_history. Id
generation now allocates under the Active lock through next_id() instead
of reading len(active_downloads) unlocked. No persistence added; in-memory
stays the only adapter.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app.py                       | 135 ++++++++++++++++++++++++++---------
 tests/conftest.py            |  10 +--
 tests/test_download_store.py | 129 +++++++++++++++++++++++++++++++++
 3 files changed, 234 insertions(+), 40 deletions(-)
 create mode 100644 tests/test_download_store.py

diff --git a/app.py b/app.py
index 42223b5..17c1d19 100644
--- a/app.py
+++ b/app.py
@@ -49,17 +49,105 @@
     logger.error("=" * 60)
 
 download_queue = queue.Queue()
-# Server is the source of truth (ADR-0002): Active + History live here in memory.
-# active_downloads maps task_id -> Download record (status: queued | downloading).
-active_downloads = {}
-active_lock = threading.Lock()
-download_history = []
-history_lock = threading.Lock()
 sse_clients = []
 album_art_cache = {}
 cache_lock = threading.Lock()
 MAX_HISTORY = 50
 
+
+class DownloadStore:
+    """Owns the server's authoritative in-memory Download state (ADR-0002):
+    the Active set (Queued + Downloading) and the terminal History, plus the
+    locks guarding them. It is the single source of truth for that state — no
+    other code touches the underlying dicts/lists directly.
+
+    The queue.Queue worker-dispatch pipe lives outside the store; the store
+    only models the Active/History lifecycle the queue feeds. The interface is
+    deliberately small (add_queued / mark_downloading / finalize / snapshot /
+    find_history) so a disk-persistence adapter could later replace it without
+    changing callers, exactly as ADR-0002 anticipated. No persistence is added
+    here: in-memory remains the only adapter.
+
+    active maps task_id -> Download record (status: queued | downloading)."""
+
+    def __init__(self, max_history=MAX_HISTORY):
+        self._max_history = max_history
+        self._active = {}
+        self._active_lock = threading.Lock()
+        self._history = []
+        self._history_lock = threading.Lock()
+        self._seq = 0
+
+    def next_id(self):
+        """Allocate a unique Download id under the Active lock, so id assignment
+        never reads Active state without holding it."""
+        with self._active_lock:
+            self._seq += 1
+            return f"dl_{int(time.time() * 1000)}_{self._seq}"
+
+    def add_queued(self, record):
+        """Record a submitted Download in Active as `queued`."""
+        with self._active_lock:
+            self._active[record["id"]] = record
+
+    def mark_downloading(self, task_id, started):
+        """Transition an existing Queued record in place to `downloading`."""
+        with self._active_lock:
+            record = self._active.get(task_id)
+            if record is not None:
+                record["status"] = "downloading"
+                record["started"] = started
+
+    def finalize(self, entry):
+        """Pop the Download from Active and prepend its terminal History entry,
+        trimming History to max_history. The Active record's url/quality/metadata
+        are folded into the entry when the caller did not supply them, because
+        Redownload re-runs a History entry from exactly those fields."""
+        task_id = entry["id"]
+        with self._active_lock:
+            record = self._active.pop(task_id, None)
+        if record is not None:
+            entry.setdefault("url", record.get("url"))
+            entry.setdefault("quality", record.get("quality"))
+            if not entry.get("metadata"):
+                entry["metadata"] = record.get("metadata", {})
+        entry.setdefault("url", None)
+        entry.setdefault("quality", None)
+        entry.setdefault("metadata", {})
+        with self._history_lock:
+            self._history.insert(0, entry)
+            del self._history[self._max_history:]
+        return entry
+
+    def snapshot(self):
+        """Return a point-in-time copy of Active (list), History (list), and the
+        queue size for /api/status rehydration."""
+        with self._active_lock:
+            active = list(self._active.values())
+        with self._history_lock:
+            history = list(self._history)
+        return {
+            "active": active,
+            "history": history,
+            "queue_size": download_queue.qsize(),
+        }
+
+    def find_history(self, entry_id):
+        """Return the History entry with this id, or None."""
+        with self._history_lock:
+            return next((e for e in self._history if e["id"] == entry_id), None)
+
+    def clear(self):
+        """Drop all Active and History state. Used by the test harness to reset
+        between tests; not part of the production lifecycle."""
+        with self._active_lock:
+            self._active.clear()
+        with self._history_lock:
+            self._history.clear()
+
+
+store = DownloadStore()
+
 # The exact line streamrip logs once per track it refuses to re-download because the
 # track is recorded in its own database. Skip detection keys on this line.
 SKIP_LINE_RE = re.compile(r"Marked as downloaded in the database")
@@ -682,8 +770,7 @@ def register_queued(task):
         "status": "queued",
         "queued_at": time.time(),
     }
-    with active_lock:
-        active_downloads[task["id"]] = record
+    store.add_queued(record)
     broadcast_sse(
         {
             "type": "download_queued",
@@ -703,7 +790,7 @@ def enqueue_download(url, quality=3, metadata=None, no_db=False):
     ``no_db`` forces a Redownload: the worker's `rip` invocation gets --no-db so
     streamrip ignores its own database and downloads an already-recorded item
     again (see the Redownload glossary entry)."""
-    task_id = f"dl_{int(time.time() * 1000)}_{len(active_downloads)}"
+    task_id = store.next_id()
     task = {
         "id": task_id,
         "url": url,
@@ -734,11 +821,7 @@ def run(self):
             no_db = task.get("no_db", False)
 
             # Transition the existing Queued card in place to Downloading.
-            with active_lock:
-                record = active_downloads.get(task_id)
-                if record is not None:
-                    record["status"] = "downloading"
-                    record["started"] = time.time()
+            store.mark_downloading(task_id, time.time())
 
             broadcast_sse(
                 {
@@ -821,14 +904,9 @@ def finalize_download(task_id, status, metadata, output, error=None):
     The History entry retains the Download's original URL and quality (taken from
     the Active record) alongside its metadata and final status, because the
     Redownload slice re-runs a History entry from exactly those fields."""
-    with active_lock:
-        record = active_downloads.pop(task_id, None)
-
     entry = {
         "id": task_id,
-        "url": record.get("url") if record else None,
-        "quality": record.get("quality") if record else None,
-        "metadata": metadata or (record.get("metadata") if record else {}),
+        "metadata": metadata or {},
         "status": status,
         "output": output,
         "completed_at": time.time(),
@@ -836,9 +914,9 @@ def finalize_download(task_id, status, metadata, output, error=None):
     if error:
         entry["error"] = error
 
-    with history_lock:
-        download_history.insert(0, entry)
-        del download_history[MAX_HISTORY:]
+    # The store pops the Active record, folds its url/quality/metadata into the
+    # entry, and trims History to MAX_HISTORY.
+    entry = store.finalize(entry)
 
     broadcast_sse(
         {
@@ -947,13 +1025,7 @@ def start_download():
 def get_all_status():
     # Server is the source of truth (ADR-0002). Active is returned as a list so the
     # frontend can rehydrate the unified Active list (Queued + Downloading) on load.
-    with active_lock:
-        active = list(active_downloads.values())
-    with history_lock:
-        history = list(download_history)
-    return jsonify(
-        {"active": active, "history": history, "queue_size": download_queue.qsize()}
-    )
+    return jsonify(store.snapshot())
 
 
 @app.route("/api/config", methods=["GET", "POST"])
@@ -1813,8 +1885,7 @@ def redownload():
     if not entry_id:
         return jsonify({"error": "History entry id is required"}), 400
 
-    with history_lock:
-        entry = next((e for e in download_history if e["id"] == entry_id), None)
+    entry = store.find_history(entry_id)
 
     if entry is None:
         return jsonify({"error": "History entry not found"}), 404
diff --git a/tests/conftest.py b/tests/conftest.py
index 34d8f48..ffc5c78 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -23,10 +23,7 @@ def clean_state():
     """Reset server-owned Active/History/queue and restore the real runner
     around every test so tests do not bleed into each other."""
     original_runner = app_module.run_rip
-    with app_module.active_lock:
-        app_module.active_downloads.clear()
-    with app_module.history_lock:
-        app_module.download_history.clear()
+    app_module.store.clear()
     # Drain any leftover queued tasks.
     try:
         while True:
@@ -47,10 +44,7 @@ def clean_state():
     # Let workers settle so they are idle before the next test reconfigures things.
     time.sleep(0.05)
     app_module.run_rip = original_runner
-    with app_module.active_lock:
-        app_module.active_downloads.clear()
-    with app_module.history_lock:
-        app_module.download_history.clear()
+    app_module.store.clear()
 
 
 def fake_runner(lines, returncode=0):
diff --git a/tests/test_download_store.py b/tests/test_download_store.py
new file mode 100644
index 0000000..6104552
--- /dev/null
+++ b/tests/test_download_store.py
@@ -0,0 +1,129 @@
+"""Unit tests for DownloadStore: the in-memory Active/History state owner.
+
+These exercise the store's lifecycle transitions directly, with no threads,
+HTTP, or queue — just the small interface (add_queued / mark_downloading /
+finalize / snapshot / find_history).
+"""
+import app as app_module
+
+
+def make_store(max_history=app_module.MAX_HISTORY):
+    return app_module.DownloadStore(max_history=max_history)
+
+
+def test_next_id_is_unique():
+    store = make_store()
+    ids = {store.next_id() for _ in range(100)}
+    assert len(ids) == 100
+
+
+def test_add_queued_appears_in_snapshot_as_queued():
+    store = make_store()
+    store.add_queued({"id": "a", "url": "u", "quality": 3, "status": "queued"})
+
+    snap = store.snapshot()
+    active = {r["id"]: r for r in snap["active"]}
+    assert active["a"]["status"] == "queued"
+    assert snap["history"] == []
+
+
+def test_mark_downloading_transitions_record_in_place():
+    store = make_store()
+    store.add_queued({"id": "a", "url": "u", "quality": 3, "status": "queued"})
+    store.mark_downloading("a", started=123.0)
+
+    active = {r["id"]: r for r in store.snapshot()["active"]}
+    assert active["a"]["status"] == "downloading"
+    assert active["a"]["started"] == 123.0
+
+
+def test_mark_downloading_unknown_id_is_a_noop():
+    store = make_store()
+    store.mark_downloading("missing", started=1.0)
+    assert store.snapshot()["active"] == []
+
+
+def test_add_mark_finalize_moves_active_to_history():
+    store = make_store()
+    store.add_queued({"id": "a", "url": "u", "quality": 4, "status": "queued"})
+    store.mark_downloading("a", started=1.0)
+
+    entry = store.finalize(
+        {"id": "a", "status": "completed", "output": "ok", "completed_at": 2.0}
+    )
+
+    # Left Active, landed in History.
+    assert store.snapshot()["active"] == []
+    history = store.snapshot()["history"]
+    assert [h["id"] for h in history] == ["a"]
+    # url/quality folded in from the popped Active record (Redownload needs them).
+    assert entry["url"] == "u"
+    assert entry["quality"] == 4
+    assert entry["status"] == "completed"
+
+
+def test_finalize_keeps_caller_supplied_metadata_over_record():
+    store = make_store()
+    store.add_queued(
+        {"id": "a", "url": "u", "quality": 3, "metadata": {"x": 1}, "status": "queued"}
+    )
+    entry = store.finalize(
+        {"id": "a", "status": "completed", "metadata": {"x": 2}, "completed_at": 1.0}
+    )
+    assert entry["metadata"] == {"x": 2}
+
+
+def test_finalize_falls_back_to_record_metadata():
+    store = make_store()
+    store.add_queued(
+        {"id": "a", "url": "u", "quality": 3, "metadata": {"x": 1}, "status": "queued"}
+    )
+    entry = store.finalize({"id": "a", "status": "completed", "completed_at": 1.0})
+    assert entry["metadata"] == {"x": 1}
+
+
+def test_finalize_without_active_record_yields_null_url_quality():
+    # A Download that was never in Active (defensive) still produces a valid entry.
+    store = make_store()
+    entry = store.finalize({"id": "gone", "status": "failed", "completed_at": 1.0})
+    assert entry["url"] is None
+    assert entry["quality"] is None
+    assert entry["metadata"] == {}
+
+
+def test_finalize_prepends_newest_first():
+    store = make_store()
+    for tid in ("a", "b", "c"):
+        store.add_queued({"id": tid, "url": "u", "quality": 3, "status": "queued"})
+        store.finalize({"id": tid, "status": "completed", "completed_at": 1.0})
+    assert [h["id"] for h in store.snapshot()["history"]] == ["c", "b", "a"]
+
+
+def test_history_is_trimmed_to_max_history():
+    store = make_store(max_history=3)
+    for i in range(10):
+        tid = f"t{i}"
+        store.add_queued({"id": tid, "url": "u", "quality": 3, "status": "queued"})
+        store.finalize({"id": tid, "status": "completed", "completed_at": float(i)})
+
+    history = store.snapshot()["history"]
+    assert len(history) == 3
+    # Newest three survive, newest first.
+    assert [h["id"] for h in history] == ["t9", "t8", "t7"]
+
+
+def test_find_history_returns_entry_or_none():
+    store = make_store()
+    store.add_queued({"id": "a", "url": "u", "quality": 3, "status": "queued"})
+    store.finalize({"id": "a", "status": "completed", "completed_at": 1.0})
+
+    found = store.find_history("a")
+    assert found is not None and found["id"] == "a"
+    assert store.find_history("nope") is None
+
+
+def test_snapshot_reports_queue_size_shape():
+    store = make_store()
+    snap = store.snapshot()
+    assert set(["active", "history", "queue_size"]) == set(snap.keys())
+    assert isinstance(snap["queue_size"], int)

From 8566e27139544aa47a7fb40da9f6d707df63f50e Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 17:03:02 +0800
Subject: [PATCH 09/12] fix: update dockerfile to use streamrip dev branch

---
 Dockerfile | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index f4ed640..adbebe4 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -15,11 +15,19 @@ RUN groupadd -g 1000 appuser && \
 # Set working directory
 WORKDIR /app
 
-# Install Python dependencies
+# Install Python dependencies. streamrip is installed from the upstream `dev`
+# branch (not the PyPI release, which lags behind): PyPI's latest is 2.1.0
+# while dev/host run 2.2.0+, and the config schema version is tied to the
+# streamrip version — a mismatch makes host and container fight over the shared
+# self-mounted config.toml (each rewrites it to its own schema on every run).
+# Tracking dev keeps the container aligned with the host build.
+# Note: `@dev` is a moving target, so rebuilds are not reproducible; Docker
+# layer caching means this only re-pulls when this layer is invalidated
+# (e.g. `--no-cache` or an earlier-layer change).
 RUN pip install --no-cache-dir \
     flask \
     flask-cors \
-    streamrip \
+    "git+https://github.com/nathom/streamrip.git@dev" \
     gunicorn \
     gevent
 

From 5c6324799b1ccd053f3a87ecd10e146dd902ea10 Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 17:28:25 +0800
Subject: [PATCH 10/12] feat: delete-album control in Library tree + compact
 search results toggle

Add a per-album DELETE control to the Files-tab tree, backed by a new
DELETE /api/library/album endpoint that confines the target to DOWNLOAD_DIR
(rejecting traversal and refusing DOWNLOAD_DIR itself), removes the folder,
and evicts its cached completeness assessment. This is the first write path
into the otherwise read-only Library (ADR-0003).

Add a COMPACT toggle to the search-controls bar that switches the results
list to a denser layout (tighter rows, no album art / ID / service chip).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app.py               | 32 +++++++++++++++++++++++
 static/css/style.css | 60 ++++++++++++++++++++++++++++++++++++++++++++
 static/js/app.js     | 35 ++++++++++++++++++++++++++
 templates/index.html |  1 +
 4 files changed, 128 insertions(+)

diff --git a/app.py b/app.py
index 17c1d19..5b578a1 100644
--- a/app.py
+++ b/app.py
@@ -1382,6 +1382,38 @@ def library_album_tracks():
         return jsonify({"error": str(e)}), 500
 
 
+@app.route("/api/library/album", methods=["DELETE"])
+def delete_library_album():
+    """Delete one album folder and everything under it from disk.
+
+    The ``path`` query parameter is the album's path relative to DOWNLOAD_DIR, as
+    returned by /api/library; it is confined to DOWNLOAD_DIR (rejecting traversal)
+    so the endpoint can only delete album folders within the Library, never
+    DOWNLOAD_DIR itself nor arbitrary directories on disk."""
+    rel_path = request.args.get("path")
+    if not rel_path:
+        return jsonify({"error": "path is required"}), 400
+
+    # Confine the resolved album folder to DOWNLOAD_DIR (reject traversal) and
+    # refuse to delete DOWNLOAD_DIR itself.
+    base = os.path.realpath(DOWNLOAD_DIR)
+    target = os.path.realpath(os.path.join(base, rel_path))
+    if target == base or not target.startswith(base + os.sep):
+        return jsonify({"error": "invalid path"}), 400
+    if not os.path.isdir(target):
+        return jsonify({"error": "album not found"}), 404
+
+    try:
+        shutil.rmtree(target)
+        # Drop any cached completeness assessment for the now-gone folder.
+        with album_cache_lock:
+            album_assessment_cache.pop(target, None)
+        return jsonify({"success": True})
+    except Exception as e:
+        logger.exception(f"Failed to delete album {rel_path}")
+        return jsonify({"error": str(e)}), 500
+
+
 class Source:
     """A single music source (Qobuz, Tidal, ...), owning everything that source
     specific: how to build a share URL from an id, how to fetch its album art,
diff --git a/static/css/style.css b/static/css/style.css
index 4085c94..51e1e01 100644
--- a/static/css/style.css
+++ b/static/css/style.css
@@ -568,6 +568,27 @@ button:disabled {
     border-color: var(--text-tertiary);
 }
 
+/* Per-album delete control, sat in the album header. Muted until hovered so it
+   stays out of the way of the (read-mostly) Library, then turns destructive-red. */
+.library-album-delete {
+    flex-shrink: 0;
+    font-size: 10px;
+    letter-spacing: 0.5px;
+    text-transform: uppercase;
+    padding: 2px 8px;
+    border: 1px solid var(--border);
+    border-radius: 2px;
+    color: var(--text-tertiary);
+    white-space: nowrap;
+    cursor: pointer;
+    transition: color 0.2s, border-color 0.2s;
+}
+
+.library-album-delete:hover {
+    color: var(--error);
+    border-color: var(--error);
+}
+
 .library-tracks {
     display: none;
     padding-left: 20px;
@@ -684,12 +705,51 @@ button:disabled {
 }
 
 .results-info {
+    display: flex;
+    align-items: center;
+    gap: 12px;
     font-size: 12px;
     color: var(--text-secondary);
     text-transform: uppercase;
     letter-spacing: 0.5px;
 }
 
+/* Toggle for the dense results layout. Muted until active, then highlighted so
+   it reads as an on/off switch. */
+.compact-toggle {
+    padding: 6px 12px;
+    font-size: 11px;
+    color: var(--text-tertiary);
+    border: 1px solid var(--border);
+    background: transparent;
+}
+
+.compact-toggle.active {
+    color: var(--accent, var(--text-primary));
+    border-color: var(--text-primary);
+}
+
+/* Compact results: tighter rows, no album art or ID line, so more fit at once. */
+.search-results.compact .search-result-item {
+    padding: 8px 12px;
+    margin-bottom: 4px;
+    gap: 12px;
+}
+
+.search-results.compact .result-album-art,
+.search-results.compact .result-id,
+.search-results.compact .result-service {
+    display: none;
+}
+
+.search-results.compact .result-title {
+    margin-bottom: 2px;
+}
+
+.search-results.compact .result-download-btn {
+    padding: 6px 14px;
+}
+
 .search-results {
     max-height: 500px;
     overflow-y: auto;
diff --git a/static/js/app.js b/static/js/app.js
index 24cbaee..f68e67e 100644
--- a/static/js/app.js
+++ b/static/js/app.js
@@ -516,6 +516,7 @@ async function loadLibrary() {
                     <span class="library-album-caret">▸</span>
                     <span class="library-album-name">${escapeHtml(album.album)}</span>
                     <span class="library-album-badge badge-pending" data-role="badge">…</span>
+                    <span class="library-album-delete" onclick="deleteAlbum(this, event)" title="Delete album from disk" role="button">DELETE</span>
                 </button>
                 <div class="library-tracks"></div>
             </div>
@@ -659,6 +660,31 @@ async function toggleAlbum(button) {
     }
 }
 
+// Delete an album folder (and everything under it) from disk. Lives on the
+// album header next to the toggle, so stop the click from also expanding the
+// album, and confirm first — this is an irreversible on-disk delete.
+async function deleteAlbum(el, event) {
+    event.stopPropagation();
+    const albumEl = el.closest('.library-album');
+    const path = albumEl.dataset.path;
+    if (!confirm(`Delete this album from disk?\n\n${path}\n\nThis permanently removes the folder and all its files and cannot be undone.`)) {
+        return;
+    }
+    try {
+        const response = await fetch('/api/library/album?path=' + encodeURIComponent(path), {
+            method: 'DELETE',
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            throw new Error(data.error || 'Failed to delete album');
+        }
+        showToast('Album deleted', 'success');
+        albumEl.remove();
+    } catch (error) {
+        showToast('Failed to delete album: ' + error.message, 'error');
+    }
+}
+
 function setSearchType(type, element) {
     currentSearchType = type;
     document.querySelectorAll('.search-type-btn').forEach(btn => btn.classList.remove('active'));
@@ -801,6 +827,15 @@ function updatePaginationControls() {
     document.getElementById('nextPage').disabled = currentPage >= totalPages;
 }
 
+// Toggle a denser layout for the results list: smaller rows with the album art
+// and ID line dropped, so more results fit on screen at once. Purely a view
+// switch — it adds/removes a class and doesn't touch the result data.
+function toggleCompactResults(button) {
+    const resultsDiv = document.getElementById('searchResults');
+    const compact = resultsDiv.classList.toggle('compact');
+    button.classList.toggle('active', compact);
+}
+
 function changePage(direction) {
     const totalPages = Math.ceil(totalResults / itemsPerPage);
     const newPage = currentPage + direction;
diff --git a/templates/index.html b/templates/index.html
index a0b0f86..d59c312 100644
--- a/templates/index.html
+++ b/templates/index.html
@@ -76,6 +76,7 @@ <h2>Search</h2>
                     <button id="nextPage" onclick="changePage(1)" disabled>NEXT</button>
                 </div>
                 <div class="results-info">
+                    <button id="compactToggle" class="compact-toggle" onclick="toggleCompactResults(this)">COMPACT</button>
                     <span id="resultsCount">0 results</span>
                 </div>
             </div>

From 4493393c74c2148b06ccce7eae256efc72bab0c2 Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 17:41:16 +0800
Subject: [PATCH 11/12] feat: stable tab-pane height, results resize button,
 custom confirm dialog

Fix the INFO box jumping on tab switch: give every .tab-content pane a fixed
height (min(520px, 65vh)) with internal scroll, so ACTIVE/HISTORY/FILES/CONFIG
all occupy the same height. Let the in-pane library tree grow instead of
opening a nested scrollbar.

Add a REDUCE SIZE / EXPAND SIZE toggle below the search results that shrinks
the results scroll window.

Replace window.confirm in the album delete flow with a reusable confirmDialog()
modal (Promise-based; cancel via button, Escape, or backdrop) styled to match
the app, with a red danger confirm button.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 static/css/style.css | 85 +++++++++++++++++++++++++++++++++++++++++++-
 static/js/app.js     | 56 ++++++++++++++++++++++++++++-
 templates/index.html | 16 +++++++++
 3 files changed, 155 insertions(+), 2 deletions(-)

diff --git a/static/css/style.css b/static/css/style.css
index 51e1e01..d13ca14 100644
--- a/static/css/style.css
+++ b/static/css/style.css
@@ -163,15 +163,25 @@ button:disabled {
     border-bottom-color: var(--accent);
 }
 
+/* Every tab pane is the same fixed height and scrolls its own overflow, so the
+   INFO box stays one size and switching tabs no longer shifts the page. */
 .tab-content {
     display: none;
-    min-height: 400px;
+    height: min(520px, 65vh);
+    overflow-y: auto;
 }
 
 .tab-content.active {
     display: block;
 }
 
+/* Inside a tab the pane already scrolls, so let these inner regions grow to
+   their content instead of opening a second, nested scrollbar. */
+.tabs-section .library-tree {
+    max-height: none;
+    overflow: visible;
+}
+
 .download-item {
     background: var(--bg-tertiary);
     border: 1px solid var(--border);
@@ -841,6 +851,79 @@ button:disabled {
     margin-top: 4px;
     font-family: 'IBM Plex Mono', monospace;
 }
+
+/* Shrink the results scroll window to a shorter pane (toggled by REDUCE SIZE). */
+.search-results.reduced {
+    max-height: 220px;
+}
+
+.search-results-footer {
+    display: flex;
+    justify-content: center;
+    margin-top: 12px;
+}
+
+.search-results-footer button {
+    font-size: 11px;
+    padding: 8px 16px;
+}
+
+/* Modal confirmation dialog (confirmDialog() in app.js), shared by destructive
+   actions such as deleting an album. */
+.modal-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 1000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 20px;
+    background: rgba(0, 0, 0, 0.7);
+}
+
+.modal-overlay[hidden] {
+    display: none;
+}
+
+.modal {
+    width: 100%;
+    max-width: 440px;
+    padding: 24px;
+    background: var(--bg-secondary, var(--bg-tertiary));
+    border: 1px solid var(--border);
+}
+
+.modal-title {
+    font-size: 14px;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+    color: var(--text-primary);
+    margin-bottom: 12px;
+}
+
+.modal-message {
+    font-size: 13px;
+    line-height: 1.5;
+    color: var(--text-secondary);
+    margin-bottom: 24px;
+    word-break: break-word;
+}
+
+.modal-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 12px;
+}
+
+.danger-btn {
+    border-color: var(--error);
+    color: var(--error);
+}
+
+.danger-btn:hover:not(:disabled) {
+    background: var(--error);
+    color: var(--bg-primary);
+}
 /* Scrollbar Styling */
 ::-webkit-scrollbar {
     width: 8px;
diff --git a/static/js/app.js b/static/js/app.js
index f68e67e..a565c55 100644
--- a/static/js/app.js
+++ b/static/js/app.js
@@ -667,7 +667,13 @@ async function deleteAlbum(el, event) {
     event.stopPropagation();
     const albumEl = el.closest('.library-album');
     const path = albumEl.dataset.path;
-    if (!confirm(`Delete this album from disk?\n\n${path}\n\nThis permanently removes the folder and all its files and cannot be undone.`)) {
+    const confirmed = await confirmDialog({
+        title: 'DELETE ALBUM',
+        message: `Permanently delete "${path}" from disk? This removes the folder and all its files and cannot be undone.`,
+        confirmLabel: 'DELETE',
+        cancelLabel: 'CANCEL',
+    });
+    if (!confirmed) {
         return;
     }
     try {
@@ -836,6 +842,54 @@ function toggleCompactResults(button) {
     button.classList.toggle('active', compact);
 }
 
+// Shrink the results pane to a shorter scroll window (and back). Just toggles a
+// class that lowers the container's max-height; the result list is untouched.
+function toggleResultsHeight(button) {
+    const resultsDiv = document.getElementById('searchResults');
+    const reduced = resultsDiv.classList.toggle('reduced');
+    button.textContent = reduced ? 'EXPAND SIZE' : 'REDUCE SIZE';
+}
+
+// A custom confirmation dialog standing in for window.confirm: returns a Promise
+// that resolves true if the user confirms, false if they cancel (button, Escape,
+// or clicking the backdrop). Only one dialog is open at a time.
+function confirmDialog({ title = 'CONFIRM', message = '', confirmLabel = 'OK', cancelLabel = 'CANCEL' } = {}) {
+    const overlay = document.getElementById('confirmOverlay');
+    const okBtn = document.getElementById('confirmOk');
+    const cancelBtn = document.getElementById('confirmCancel');
+
+    document.getElementById('confirmTitle').textContent = title;
+    document.getElementById('confirmMessage').textContent = message;
+    okBtn.textContent = confirmLabel;
+    cancelBtn.textContent = cancelLabel;
+
+    return new Promise(resolve => {
+        const close = result => {
+            overlay.hidden = true;
+            okBtn.removeEventListener('click', onOk);
+            cancelBtn.removeEventListener('click', onCancel);
+            overlay.removeEventListener('click', onBackdrop);
+            document.removeEventListener('keydown', onKey);
+            resolve(result);
+        };
+        const onOk = () => close(true);
+        const onCancel = () => close(false);
+        const onBackdrop = e => { if (e.target === overlay) close(false); };
+        const onKey = e => {
+            if (e.key === 'Escape') close(false);
+            else if (e.key === 'Enter') close(true);
+        };
+
+        okBtn.addEventListener('click', onOk);
+        cancelBtn.addEventListener('click', onCancel);
+        overlay.addEventListener('click', onBackdrop);
+        document.addEventListener('keydown', onKey);
+
+        overlay.hidden = false;
+        okBtn.focus();
+    });
+}
+
 function changePage(direction) {
     const totalPages = Math.ceil(totalResults / itemsPerPage);
     const newPage = currentPage + direction;
diff --git a/templates/index.html b/templates/index.html
index d59c312..2c7a89b 100644
--- a/templates/index.html
+++ b/templates/index.html
@@ -84,6 +84,9 @@ <h2>Search</h2>
             <div id="searchResults" class="search-results">
                 <div class="empty-state">ENTER A SEARCH QUERY ABOVE</div>
             </div>
+            <div class="search-results-footer">
+                <button id="resizeResults" class="secondary-btn" onclick="toggleResultsHeight(this)">REDUCE SIZE</button>
+            </div>
         </div>
         
         <!-- Tabs Section -->
@@ -130,6 +133,19 @@ <h2>INFO</h2>
 
     <div id="toastContainer" class="toast-container" aria-live="polite" aria-atomic="false"></div>
 
+    <!-- Reusable confirmation dialog (see confirmDialog() in app.js). Hidden until
+         a caller opens it; its title/message/buttons are filled in at open time. -->
+    <div id="confirmOverlay" class="modal-overlay" hidden>
+        <div class="modal" role="alertdialog" aria-modal="true" aria-labelledby="confirmTitle" aria-describedby="confirmMessage">
+            <div id="confirmTitle" class="modal-title">CONFIRM</div>
+            <div id="confirmMessage" class="modal-message"></div>
+            <div class="modal-actions">
+                <button id="confirmCancel" class="secondary-btn">CANCEL</button>
+                <button id="confirmOk" class="danger-btn">DELETE</button>
+            </div>
+        </div>
+    </div>
+
     <script src="{{ url_for('static', filename='js/app.js') }}"></script>
 </body>
 </html>

From 944deec7f988a6d0689c855c25c3fc1d1602caa0 Mon Sep 17 00:00:00 2001
From: QuantumFF <jonathanczt@gmail.com>
Date: Sun, 7 Jun 2026 17:46:10 +0800
Subject: [PATCH 12/12] fix: run a single gunicorn worker so downloads show in
 Active/History
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Active/History state, the SSE subscriber list, and the download worker
threads all live in-process (ADR-0002). With --workers 2 each gunicorn
worker is a separate process with its own copy of all three, so the
browser's SSE stream and the request that starts a download can land on
different workers — the download runs but never appears in Active/History.
Drop to one gevent worker, which serves many concurrent SSE clients via
greenlets while download concurrency stays handled by MAX_CONCURRENT_DOWNLOADS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 Dockerfile | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index adbebe4..db73517 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -46,5 +46,12 @@ USER 1000:1000
 # Expose port
 EXPOSE 5000
 
-# Run with aggressive worker recycling
-CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--worker-class", "gevent", "--workers", "2", "--timeout", "60", "app:app"]
+# Single worker only: Active/History state, the SSE subscriber list, and the
+# download worker threads all live in-process (ADR-0002). A second gunicorn
+# worker is a separate process with its own copy of all three, so the browser's
+# SSE stream and the request that starts a download can land on different
+# workers — the download runs but never shows up in Active/History. The gevent
+# worker class serves many concurrent SSE clients in this one process via
+# greenlets, and download concurrency is handled internally by
+# MAX_CONCURRENT_DOWNLOADS worker threads, so one worker loses nothing.
+CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--worker-class", "gevent", "--workers", "1", "--timeout", "60", "app:app"]