diff --git a/tests/static/test_discover_section_controller.mjs b/tests/static/test_discover_section_controller.mjs
new file mode 100644
index 00000000..8cc1b655
--- /dev/null
+++ b/tests/static/test_discover_section_controller.mjs
@@ -0,0 +1,707 @@
+// Tests for `createDiscoverSectionController` in
+// `webui/static/discover-section-controller.js`. Run via:
+//
+// node --test tests/static/
+//
+// Or through the Python wrapper at
+// tests/test_discover_section_controller_js.py which shells out to
+// `node --test` and surfaces the result inside the regular pytest run.
+//
+// The controller is loaded into a sandboxed `vm` context with stubbed
+// `window` / `document` / `Element` / `fetch`. No DOM or network — just
+// the lifecycle contract.
+
+import { test, describe, before } from 'node:test';
+import assert from 'node:assert/strict';
+import vm from 'node:vm';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONTROLLER_PATH = resolve(__dirname, '..', '..', 'webui', 'static', 'discover-section-controller.js');
+
+// Minimal Element stub — controller uses `instanceof Element` to tell
+// strings (selectors) apart from DOM refs.
+class Element {
+ constructor(id) {
+ this.id = id;
+ this.innerHTML = '';
+ this.style = { display: '' };
+ }
+}
+
+// Build a fresh sandbox per test so state doesn't leak between cases.
+function makeSandbox(opts = {}) {
+ const elements = new Map();
+ const ensureEl = (sel) => {
+ if (!elements.has(sel)) elements.set(sel, new Element(sel));
+ return elements.get(sel);
+ };
+
+ const sandbox = {
+ Element,
+ window: {},
+ console: {
+ // Quiet by default — turn on by passing { logCalls: true }
+ debug: opts.logCalls ? console.debug : () => {},
+ error: opts.logCalls ? console.error : () => {},
+ log: opts.logCalls ? console.log : () => {},
+ },
+ document: {
+ querySelector: (sel) => ensureEl(sel),
+ },
+ fetch: opts.fetch || (async () => {
+ throw new Error('fetch not stubbed for this test');
+ }),
+ // Toast spy — when controller calls window.showToast, capture it
+ _toasts: [],
+ };
+ sandbox.window.showToast = (msg, type) => sandbox._toasts.push({ msg, type });
+ sandbox._elements = elements;
+ return sandbox;
+}
+
+let CONTROLLER_SOURCE;
+before(() => {
+ CONTROLLER_SOURCE = readFileSync(CONTROLLER_PATH, 'utf8');
+});
+
+function loadController(sandbox) {
+ vm.createContext(sandbox);
+ vm.runInContext(CONTROLLER_SOURCE, sandbox);
+ return sandbox.window.createDiscoverSectionController;
+}
+
+// =========================================================================
+// Config validation
+// =========================================================================
+
+describe('config validation', () => {
+ test('throws on missing id', () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ assert.throws(() => create({
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: () => [],
+ renderItems: () => '',
+ }), /config.id required/);
+ });
+
+ test('throws on missing contentEl', () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ assert.throws(() => create({
+ id: 'x',
+ fetchUrl: '/u',
+ extractItems: () => [],
+ renderItems: () => '',
+ }), /contentEl required/);
+ });
+
+ test('throws when both fetchUrl and data provided', () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ assert.throws(() => create({
+ id: 'x',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ data: { ok: true },
+ extractItems: () => [],
+ renderItems: () => '',
+ }), /mutually exclusive/);
+ });
+
+ test('throws when neither fetchUrl nor data provided', () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ assert.throws(() => create({
+ id: 'x',
+ contentEl: '#x',
+ extractItems: () => [],
+ renderItems: () => '',
+ }), /either config.fetchUrl or config.data required/);
+ });
+
+ test('throws when extractItems missing', () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ assert.throws(() => create({
+ id: 'x',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ renderItems: () => '',
+ }), /extractItems required/);
+ });
+
+ test('throws when renderItems missing', () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ assert.throws(() => create({
+ id: 'x',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: () => [],
+ }), /renderItems required/);
+ });
+
+ test('accepts function fetchUrl', () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ assert.doesNotThrow(() => create({
+ id: 'x',
+ contentEl: '#x',
+ fetchUrl: () => '/u',
+ extractItems: () => [],
+ renderItems: () => '',
+ }));
+ });
+
+ test('accepts data instead of fetchUrl', () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ assert.doesNotThrow(() => create({
+ id: 'x',
+ contentEl: '#x',
+ data: { ok: true },
+ extractItems: () => [],
+ renderItems: () => '',
+ }));
+ });
+});
+
+// =========================================================================
+// Happy path — fetch → render
+// =========================================================================
+
+describe('fetch + render lifecycle', () => {
+ test('fetches, parses, calls renderItems, writes innerHTML', async () => {
+ const sandbox = makeSandbox({
+ fetch: async (url) => {
+ assert.equal(url, '/api/test');
+ return {
+ ok: true,
+ json: async () => ({ success: true, items: [{ id: 1 }, { id: 2 }] }),
+ };
+ },
+ });
+ const create = loadController(sandbox);
+ let renderCalls = 0;
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#carousel',
+ fetchUrl: '/api/test',
+ extractItems: (data) => data.items,
+ renderItems: (items) => {
+ renderCalls++;
+ return `${items.length}`;
+ },
+ });
+ await ctrl.load();
+ assert.equal(renderCalls, 1);
+ assert.equal(sandbox._elements.get('#carousel').innerHTML, '2');
+ assert.equal(ctrl.getState().phase, 'rendered');
+ });
+
+ test('fires onRendered hook after render', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({
+ ok: true,
+ json: async () => ({ success: true, items: [{ id: 1 }] }),
+ }),
+ });
+ const create = loadController(sandbox);
+ let hookCalls = 0;
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => 'rendered',
+ onRendered: (ctx) => {
+ hookCalls++;
+ assert.ok(ctx.contentEl);
+ assert.ok(ctx.items);
+ assert.ok(ctx.data);
+ },
+ });
+ await ctrl.load();
+ assert.equal(hookCalls, 1);
+ });
+
+ test('fires onSuccess hook after success gate, before render', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({
+ ok: true,
+ json: async () => ({ success: true, items: [], stats: { count: 5 } }),
+ }),
+ });
+ const create = loadController(sandbox);
+ const order = [];
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => { order.push('render'); return ''; },
+ onSuccess: (data) => { order.push(`success:${data.stats.count}`); },
+ });
+ await ctrl.load();
+ // Empty items → no render. onSuccess still fires.
+ assert.deepEqual(order, ['success:5']);
+ });
+
+ test('fires beforeLoad hook before spinner shows', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({
+ ok: true,
+ json: async () => ({ success: true, items: [{ id: 1 }] }),
+ }),
+ });
+ const create = loadController(sandbox);
+ const order = [];
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => { order.push('render'); return 'r'; },
+ beforeLoad: () => { order.push('before'); },
+ });
+ await ctrl.load();
+ assert.equal(order[0], 'before');
+ assert.equal(order[1], 'render');
+ });
+});
+
+// =========================================================================
+// Empty state
+// =========================================================================
+
+describe('empty state', () => {
+ test('renders empty message when items array is empty', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [] }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => '',
+ emptyMessage: 'Nothing here',
+ });
+ await ctrl.load();
+ const html = sandbox._elements.get('#x').innerHTML;
+ assert.match(html, /Nothing here/);
+ assert.doesNotMatch(html, /should-not-appear/);
+ assert.equal(ctrl.getState().phase, 'empty');
+ });
+
+ test('hides whole section when hideWhenEmpty + empty', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [] }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ sectionEl: '#wrapper',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => '',
+ hideWhenEmpty: true,
+ });
+ await ctrl.load();
+ assert.equal(sandbox._elements.get('#wrapper').style.display, 'none');
+ });
+
+ test('treats success=false as empty (default)', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: false, items: [{ id: 1 }] }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => '',
+ emptyMessage: 'X',
+ });
+ await ctrl.load();
+ assert.equal(ctrl.getState().phase, 'empty');
+ });
+
+ test('custom isSuccess overrides default success-flag check', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ status: 'ok', items: [{ id: 1 }] }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ isSuccess: (d) => d.status === 'ok',
+ renderItems: (items) => `r:${items.length}`,
+ });
+ await ctrl.load();
+ assert.equal(sandbox._elements.get('#x').innerHTML, 'r:1');
+ });
+});
+
+// =========================================================================
+// Stale state
+// =========================================================================
+
+describe('stale state', () => {
+ test('renders stale UI + fires onStale when isStale returns true', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [], stale: true }) }),
+ });
+ const create = loadController(sandbox);
+ let staleHookCalled = false;
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ isStale: (items, data) => data.stale && items.length === 0,
+ renderItems: () => '',
+ staleMessage: 'Updating from upstream',
+ onStale: () => { staleHookCalled = true; },
+ });
+ await ctrl.load();
+ assert.equal(ctrl.getState().phase, 'stale');
+ assert.equal(staleHookCalled, true);
+ assert.match(sandbox._elements.get('#x').innerHTML, /Updating from upstream/);
+ });
+
+ test('stale wins over empty when both apply', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [], stale: true }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ isStale: () => true,
+ renderItems: () => '',
+ emptyMessage: 'EMPTY',
+ staleMessage: 'STALE',
+ });
+ await ctrl.load();
+ const html = sandbox._elements.get('#x').innerHTML;
+ assert.match(html, /STALE/);
+ assert.doesNotMatch(html, /EMPTY/);
+ });
+
+ test('custom renderStale overrides default stale UI', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [], stale: true }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ isStale: () => true,
+ renderItems: () => '',
+ renderStale: () => '',
+ });
+ await ctrl.load();
+ assert.equal(sandbox._elements.get('#x').innerHTML, '');
+ });
+});
+
+// =========================================================================
+// Error state
+// =========================================================================
+
+describe('error state', () => {
+ test('renders error block on HTTP non-ok', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: false, status: 500, json: async () => ({}) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => '',
+ errorMessage: 'load failed',
+ });
+ await ctrl.load();
+ assert.equal(ctrl.getState().phase, 'error');
+ assert.match(sandbox._elements.get('#x').innerHTML, /load failed/);
+ });
+
+ test('renders error block when fetch throws', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => { throw new Error('network down'); },
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => '',
+ errorMessage: 'oops',
+ });
+ await ctrl.load();
+ assert.equal(ctrl.getState().phase, 'error');
+ assert.match(sandbox._elements.get('#x').innerHTML, /oops/);
+ });
+
+ test('fires showToast on error when showErrorToast: true', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => { throw new Error('boom'); },
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => '',
+ errorMessage: 'load broke',
+ showErrorToast: true,
+ });
+ await ctrl.load();
+ assert.equal(sandbox._toasts.length, 1);
+ assert.equal(sandbox._toasts[0].msg, 'load broke');
+ assert.equal(sandbox._toasts[0].type, 'error');
+ });
+
+ test('does NOT fire toast when showErrorToast omitted', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => { throw new Error('boom'); },
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => '',
+ });
+ await ctrl.load();
+ assert.equal(sandbox._toasts.length, 0);
+ });
+});
+
+// =========================================================================
+// No-fetch data: mode
+// =========================================================================
+
+describe('no-fetch data mode', () => {
+ test('renders provided data without calling fetch', async () => {
+ let fetchCalled = false;
+ const sandbox = makeSandbox({
+ fetch: async () => { fetchCalled = true; throw new Error('should not fetch'); },
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ data: { success: true, items: [{ id: 1 }, { id: 2 }] },
+ extractItems: (d) => d.items,
+ renderItems: (items) => `n:${items.length}`,
+ });
+ await ctrl.load();
+ assert.equal(fetchCalled, false);
+ assert.equal(sandbox._elements.get('#x').innerHTML, 'n:2');
+ });
+
+ test('accepts data as a function', async () => {
+ const sandbox = makeSandbox();
+ const create = loadController(sandbox);
+ let dataCalls = 0;
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ data: () => { dataCalls++; return { success: true, items: [{ id: 9 }] }; },
+ extractItems: (d) => d.items,
+ renderItems: (items) => `f:${items[0].id}`,
+ });
+ await ctrl.load();
+ assert.equal(dataCalls, 1);
+ assert.equal(sandbox._elements.get('#x').innerHTML, 'f:9');
+ });
+});
+
+// =========================================================================
+// manualDom mode
+// =========================================================================
+
+describe('manualDom mode', () => {
+ test('does NOT write renderItems return into contentEl', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [{ id: 1 }] }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ manualDom: true,
+ extractItems: (d) => d.items,
+ renderItems: () => '',
+ });
+ await ctrl.load();
+ const html = sandbox._elements.get('#x').innerHTML;
+ // Spinner from _showLoading was the last write; manualDom mode
+ // didn't replace it. The renderer gets called for side-effects
+ // (which the test doesn't exercise here) but innerHTML stays
+ // whatever the loading spinner left.
+ assert.doesNotMatch(html, /should-not-appear/);
+ assert.equal(ctrl.getState().phase, 'rendered');
+ });
+
+ test('still fires renderItems for side-effects', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [{ id: 1 }] }) }),
+ });
+ const create = loadController(sandbox);
+ let renderCalled = false;
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ manualDom: true,
+ extractItems: (d) => d.items,
+ renderItems: () => { renderCalled = true; },
+ });
+ await ctrl.load();
+ assert.equal(renderCalled, true);
+ });
+});
+
+// =========================================================================
+// Fetch URL forms
+// =========================================================================
+
+describe('fetchUrl forms', () => {
+ test('callable fetchUrl is invoked at load time', async () => {
+ let urlCalls = 0;
+ const sandbox = makeSandbox({
+ fetch: async (url) => {
+ assert.equal(url, '/u/computed');
+ return { ok: true, json: async () => ({ success: true, items: [{ id: 1 }] }) };
+ },
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: () => { urlCalls++; return '/u/computed'; },
+ extractItems: (d) => d.items,
+ renderItems: () => 'r',
+ });
+ await ctrl.load();
+ assert.equal(urlCalls, 1);
+ // Calling refresh re-resolves the URL — important for sections
+ // whose URL depends on runtime state (e.g. season key).
+ await ctrl.refresh();
+ assert.equal(urlCalls, 2);
+ });
+});
+
+// =========================================================================
+// Coalescing + refresh
+// =========================================================================
+
+describe('load coalescing and refresh', () => {
+ test('two concurrent load() calls share one fetch', async () => {
+ let fetchCalls = 0;
+ const sandbox = makeSandbox({
+ fetch: async () => {
+ fetchCalls++;
+ // Yield once so both load() calls land on the same in-flight promise.
+ await new Promise((r) => setImmediate(r));
+ return { ok: true, json: async () => ({ success: true, items: [{ id: 1 }] }) };
+ },
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => 'r',
+ });
+ await Promise.all([ctrl.load(), ctrl.load(), ctrl.load()]);
+ assert.equal(fetchCalls, 1);
+ });
+
+ test('refresh() bypasses the coalesce and re-fetches', async () => {
+ let fetchCalls = 0;
+ const sandbox = makeSandbox({
+ fetch: async () => {
+ fetchCalls++;
+ return { ok: true, json: async () => ({ success: true, items: [{ id: 1 }] }) };
+ },
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => 'r',
+ });
+ await ctrl.load();
+ await ctrl.refresh();
+ await ctrl.refresh();
+ assert.equal(fetchCalls, 3);
+ });
+});
+
+// =========================================================================
+// Hook error containment
+// =========================================================================
+
+describe('hook error containment', () => {
+ test('throwing renderer hook does not crash the controller', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [{ id: 1 }] }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => 'r',
+ onRendered: () => { throw new Error('hook boom'); },
+ });
+ // Test passes if this doesn't throw out of the await.
+ await ctrl.load();
+ assert.equal(ctrl.getState().phase, 'rendered');
+ });
+
+ test('throwing onSuccess hook does not block the render', async () => {
+ const sandbox = makeSandbox({
+ fetch: async () => ({ ok: true, json: async () => ({ success: true, items: [{ id: 1 }] }) }),
+ });
+ const create = loadController(sandbox);
+ const ctrl = create({
+ id: 'test',
+ contentEl: '#x',
+ fetchUrl: '/u',
+ extractItems: (d) => d.items,
+ renderItems: () => 'rendered-anyway',
+ onSuccess: () => { throw new Error('boom'); },
+ });
+ await ctrl.load();
+ assert.equal(sandbox._elements.get('#x').innerHTML, 'rendered-anyway');
+ });
+});
diff --git a/tests/test_discover_section_controller_js.py b/tests/test_discover_section_controller_js.py
new file mode 100644
index 00000000..8ebcd1d1
--- /dev/null
+++ b/tests/test_discover_section_controller_js.py
@@ -0,0 +1,76 @@
+"""Run the JS tests for `webui/static/discover-section-controller.js`
+under the regular pytest sweep.
+
+The actual contract tests live in
+`tests/static/test_discover_section_controller.mjs` and run via
+Node.js's stable built-in test runner (`node --test`). This shim
+shells out to that runner and asserts a clean exit so the JS tests
+fail the suite if the controller contract drifts.
+
+Skipped when:
+ - `node` isn't on PATH (e.g. Python-only dev container).
+ - Node version < 22 (the built-in `--test` runner went stable in 18
+ but the assert-flavor we use is 22+).
+
+Run directly:
+ node --test tests/static/test_discover_section_controller.mjs
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+_TEST_FILE = _REPO_ROOT / "tests" / "static" / "test_discover_section_controller.mjs"
+
+
+def _node_available() -> bool:
+ if not shutil.which("node"):
+ return False
+ try:
+ result = subprocess.run(
+ ["node", "--version"],
+ capture_output=True, text=True, timeout=10,
+ )
+ except (subprocess.SubprocessError, FileNotFoundError):
+ return False
+ if result.returncode != 0:
+ return False
+ # Output looks like "v22.21.0"
+ raw = (result.stdout or "").strip().lstrip("v")
+ try:
+ major = int(raw.split(".")[0])
+ except (ValueError, IndexError):
+ return False
+ return major >= 22
+
+
+def test_discover_section_controller_js():
+ """Pin the JS controller's lifecycle contract via `node --test`."""
+ if not _node_available():
+ pytest.skip("Node.js >= 22 required to run the JS controller tests")
+
+ if not _TEST_FILE.exists():
+ pytest.skip(f"JS test file missing: {_TEST_FILE}")
+
+ result = subprocess.run(
+ ["node", "--test", str(_TEST_FILE)],
+ capture_output=True, text=True,
+ cwd=str(_REPO_ROOT),
+ timeout=60,
+ )
+
+ if result.returncode != 0:
+ # Surface the node test runner output so failures are
+ # debuggable from the pytest log without re-running by hand.
+ pytest.fail(
+ "JS controller tests failed:\n\n"
+ f"--- stdout ---\n{result.stdout}\n"
+ f"--- stderr ---\n{result.stderr}",
+ pytrace=False,
+ )
diff --git a/webui/index.html b/webui/index.html
index 3de06f8e..7b0d993a 100644
--- a/webui/index.html
+++ b/webui/index.html
@@ -7908,6 +7908,7 @@
+
diff --git a/webui/static/discover-section-controller.js b/webui/static/discover-section-controller.js
new file mode 100644
index 00000000..fc60635b
--- /dev/null
+++ b/webui/static/discover-section-controller.js
@@ -0,0 +1,452 @@
+/**
+ * Discover Section Controller
+ * ---------------------------
+ *
+ * Owns the lifecycle every discover-page section already does by hand:
+ *
+ * 1. show a loading spinner in the carousel container
+ * 2. fetch the section's endpoint (or use pre-fetched data)
+ * 3. parse the response, decide whether the data is empty
+ * 4. either show the empty state, render the items, show a stale
+ * "still updating" state, or show an error
+ * 5. wire any post-render handlers (download buttons, hover, etc)
+ * 6. expose a refresh() method so the same lifecycle can re-fire
+ *
+ * Each section currently re-implements this by hand in `discover.js`
+ * with subtle drift — different empty-state messages, inconsistent
+ * error handling, inconsistent refresh-button feedback, no consistent
+ * error toast. This controller is the "lift what's truly shared"
+ * extraction: register a section once, the controller handles the
+ * lifecycle, the section provides only its renderer.
+ *
+ * Renderers stay per-section because section data shapes legitimately
+ * differ (album cards vs artist circles vs playlist tiles vs track
+ * rows). The controller is the lifecycle wrapper around those
+ * renderers, not a forced visual abstraction.
+ *
+ * USAGE:
+ *
+ * const ctrl = createDiscoverSectionController({
+ * id: 'recent-releases',
+ * contentEl: '#recent-releases-carousel',
+ * fetchUrl: '/api/discover/recent-releases',
+ * extractItems: (data) => data.albums || [],
+ * renderItems: (items, data, ctx) => buildCardsHtml(items),
+ * onRendered: (ctx) => attachClickHandlers(ctx.contentEl),
+ * loadingMessage: 'Loading recent releases...',
+ * emptyMessage: 'No recent releases found',
+ * errorMessage: 'Failed to load recent releases',
+ * });
+ * ctrl.load();
+ *
+ * EXTENSIONS:
+ *
+ * `fetchUrl` accepts a function returning a string for sections
+ * whose endpoint depends on runtime state (e.g. seasonal playlist
+ * keyed by `currentSeasonKey`).
+ *
+ * `data` lets a section bypass fetch entirely — the controller still
+ * runs success / empty / render / onRendered, just without going to
+ * the network. Use when a parent already fetched and just wants the
+ * shared lifecycle. `data` may be a value or a `() => value`
+ * function. Sections must supply EITHER `fetchUrl` OR `data`, not
+ * both.
+ *
+ * `beforeLoad(ctx)` runs before the spinner shows. Useful for
+ * ensuring `contentEl` exists (e.g. dynamically inserted sections)
+ * or updating sibling headers / subtitles before any visual change.
+ *
+ * `onSuccess(data, ctx)` runs after the success check passes but
+ * before isEmpty / isStale checks. Cleaner home for header text
+ * updates that depend on response data (vs folding them into
+ * renderItems).
+ *
+ * `isStale(items, data)` + `onStale(ctx)` give sections a third
+ * render state for "data is empty but the upstream is still
+ * discovering". Returning true from `isStale` renders the stale
+ * state (default: spinner + "Updating..." copy, override via
+ * `renderStale` or `staleMessage`) and fires `onStale` so the
+ * section can start a poller. Stale wins over empty when both apply.
+ *
+ * `showErrorToast: true` opens a global `showToast(...)` on error
+ * in addition to the in-section error block. Default off — sections
+ * that have no recovery action shouldn't shout at the user.
+ *
+ * `manualDom: true` tells the controller to NOT write the
+ * `renderItems` return value into `contentEl`. The renderer takes
+ * full responsibility for the DOM (e.g. delegating to an existing
+ * grid renderer that targets a child element). The renderer is
+ * still called, just for its side-effects. Default false.
+ */
+
+(function () {
+ 'use strict';
+
+ function _validateConfig(cfg) {
+ if (!cfg || typeof cfg !== 'object') {
+ throw new Error('createDiscoverSectionController: config required');
+ }
+ if (typeof cfg.id !== 'string' || !cfg.id) {
+ throw new Error('createDiscoverSectionController: config.id required (string)');
+ }
+ if (typeof cfg.contentEl !== 'string' && !(cfg.contentEl instanceof Element)) {
+ throw new Error(`[discover:${cfg.id}] config.contentEl required (selector or Element)`);
+ }
+ const hasFetch = (typeof cfg.fetchUrl === 'string' && cfg.fetchUrl) || typeof cfg.fetchUrl === 'function';
+ const hasData = cfg.data !== undefined;
+ if (!hasFetch && !hasData) {
+ throw new Error(`[discover:${cfg.id}] either config.fetchUrl or config.data required`);
+ }
+ if (hasFetch && hasData) {
+ throw new Error(`[discover:${cfg.id}] config.fetchUrl and config.data are mutually exclusive`);
+ }
+ if (typeof cfg.renderItems !== 'function') {
+ throw new Error(`[discover:${cfg.id}] config.renderItems required (function)`);
+ }
+ // Cin standard — explicit > implicit. Each section knows its own
+ // response shape; the controller refusing to guess prevents
+ // silent wrong-key bugs (e.g. an endpoint that returns
+ // `data.results` getting auto-pulled instead of the intended
+ // `data.tracks`).
+ if (typeof cfg.extractItems !== 'function') {
+ throw new Error(`[discover:${cfg.id}] config.extractItems required (function returning array)`);
+ }
+ }
+
+ function _resolveEl(el) {
+ if (el instanceof Element) return el;
+ if (typeof el === 'string') return document.querySelector(el);
+ return null;
+ }
+
+ /**
+ * @param {Object} cfg - Section config (see file header for shape)
+ * @returns {Object} Public API: { load, refresh, destroy, getState }
+ */
+ function createDiscoverSectionController(cfg) {
+ _validateConfig(cfg);
+
+ const config = Object.assign({
+ sectionEl: null,
+ hideWhenEmpty: false,
+ renderEmptyState: true,
+ fetchMethod: 'GET',
+ fetchOptions: null,
+ // Either fetchUrl (string or () => string) or data
+ // (value or () => value). Validated mutually exclusive above.
+ extractItems: null,
+ isSuccess: null,
+ isEmpty: null,
+ // Stale = data is empty but upstream is still discovering.
+ // Returning true here renders the stale state instead of
+ // empty, and fires onStale so the section can poll.
+ isStale: null,
+ renderStale: null,
+ staleMessage: 'Updating...',
+ // Hooks
+ beforeLoad: null, // (ctx) => void — before spinner shows
+ onSuccess: null, // (data, ctx) => void — after success gate
+ onStale: null, // (ctx) => void — when stale state renders
+ onRendered: null, // (ctx) => void — after content renders
+ // UX copy
+ loadingMessage: 'Loading...',
+ emptyMessage: 'Nothing to show',
+ errorMessage: 'Failed to load',
+ loadingClass: 'discover-loading',
+ emptyClass: 'discover-empty',
+ errorClass: 'discover-empty',
+ staleClass: 'discover-loading',
+ // Errors
+ verboseErrors: false,
+ showErrorToast: false, // also fire window.showToast on error
+ // Renderer takes responsibility for the DOM — controller
+ // calls renderItems but does NOT write its return value
+ // into contentEl. Use when delegating to an existing
+ // renderer that targets a child element.
+ manualDom: false,
+ }, cfg);
+
+ const state = {
+ phase: 'idle', // idle | loading | rendered | empty | stale | error
+ lastData: null,
+ lastError: null,
+ inFlight: null,
+ };
+
+ function _setHtml(el, html) {
+ if (el) el.innerHTML = html;
+ }
+
+ function _ctx(extra) {
+ return Object.assign(
+ { contentEl: _resolveEl(config.contentEl), config },
+ extra || {},
+ );
+ }
+
+ function _showLoading() {
+ const contentEl = _resolveEl(config.contentEl);
+ if (!contentEl) return;
+ const msg = config.loadingMessage
+ ? `${config.loadingMessage}
`
+ : '';
+ _setHtml(contentEl, `
+
+ `);
+ state.phase = 'loading';
+ }
+
+ function _showEmpty() {
+ const contentEl = _resolveEl(config.contentEl);
+ if (!contentEl) return;
+ if (config.hideWhenEmpty) {
+ const sectionEl = _resolveEl(config.sectionEl);
+ if (sectionEl) sectionEl.style.display = 'none';
+ state.phase = 'empty';
+ return;
+ }
+ if (config.renderEmptyState) {
+ _setHtml(contentEl, `
+
+
${config.emptyMessage}
+
+
+
${config.staleMessage}
+
+
${config.errorMessage}
+
Loading recent releases...
+
+
+
+
+
${album.album_name}
+
${album.artist_name}
+
${album.release_date}
+
+
-
-
-
-
-
${album.album_name}
-
${album.artist_name}
-
${album.release_date}
-
-
Failed to load recent releases
Fetching your albums from connected services...
Fetching your albums from connected services...
No new releases available
+
${index + 1}
+
+
+
+
+
${track.track_name}
+
${track.artist_name}
+
+
${track.album_name}
+
${duration}
+
';
- data.tracks.forEach((track, index) => {
- const coverUrl = track.album_cover_url || '/static/placeholder-album.png';
- const durationMin = Math.floor(track.duration_ms / 60000);
- const durationSec = Math.floor((track.duration_ms % 60000) / 1000);
- const duration = `${durationMin}:${durationSec.toString().padStart(2, '0')}`;
+let _releaseRadarCtrl = null;
- html += `
-
-
${index + 1}
-
-
-
-
-
${track.track_name}
-
${track.artist_name}
-
-
${track.album_name}
-
${duration}
-
- `;
+async function loadDiscoverReleaseRadar() {
+ if (!_releaseRadarCtrl) {
+ _releaseRadarCtrl = createDiscoverSectionController({
+ id: 'release-radar',
+ contentEl: '#release-radar-playlist',
+ fetchUrl: '/api/discover/release-radar',
+ extractItems: (data) => data.tracks || [],
+ renderItems: (items) => {
+ discoverReleaseRadarTracks = items;
+ const rows = items.map((t, i) => _renderCompactTrackRow(t, i)).join('');
+ return `
${rows}
`;
+ },
+ loadingMessage: 'Loading release radar...',
+ emptyMessage: 'No new releases available',
+ errorMessage: 'Failed to load release radar',
+ verboseErrors: true,
+ showErrorToast: true,
});
- html += '
Failed to load release radar
Curating your discovery playlist...
';
- data.tracks.forEach((track, index) => {
- const coverUrl = track.album_cover_url || '/static/placeholder-album.png';
- const durationMin = Math.floor(track.duration_ms / 60000);
- const durationSec = Math.floor((track.duration_ms % 60000) / 1000);
- const duration = `${durationMin}:${durationSec.toString().padStart(2, '0')}`;
+let _weeklyCtrl = null;
- html += `
-
-
${index + 1}
-
-
-
-
-
${track.track_name}
-
${track.artist_name}
-
-
${track.album_name}
-
${duration}
-
- `;
+async function loadDiscoverWeekly() {
+ if (!_weeklyCtrl) {
+ _weeklyCtrl = createDiscoverSectionController({
+ id: 'discovery-weekly',
+ contentEl: '#discovery-weekly-playlist',
+ fetchUrl: '/api/discover/weekly',
+ extractItems: (data) => data.tracks || [],
+ renderItems: (items) => {
+ discoverWeeklyTracks = items;
+ const rows = items.map((t, i) => _renderCompactTrackRow(t, i)).join('');
+ return `
${rows}
`;
+ },
+ loadingMessage: 'Curating your discovery playlist...',
+ emptyMessage: 'No tracks available yet',
+ errorMessage: 'Failed to load discovery weekly',
+ verboseErrors: true,
+ showErrorToast: true,
});
- html += '
Failed to load discovery weekly
+
+
+
${label}
+
${decade.track_count} tracks
+
Classics
+
+
No decade content available yet. Run a watchlist scan to populate your discovery pool!
-
-
-
${label}
-
${decade.track_count} tracks
-
Classics
-
-
+
+
+
${displayName}
+
${genre.track_count} tracks
+
Curated
+
+
No genre content available yet. Run a watchlist scan to populate your discovery pool!
-
-
-
${displayName}
-
${genre.track_count} tracks
-
Curated
-
-
+
+
+ ⟳
+ Syncing to media server...
+
+
+ ✓ 0
+ ⏳ 0
+ ✗ 0
+ (0%)
+
+
+
-
-
- ⟳
- Syncing to media server...
-
-
- ✓ 0
- ⏳ 0
- ✗ 0
- (0%)
-
-
-
-
-
- ⟳
- Syncing to media server...
-
-
- ✓ 0
- ⏳ 0
- ✗ 0
- (0%)
-
-
-
-
-
-
-
-
${album.album_name}
-
${album.artist_name}
- ${album.release_date ? `
${album.release_date}
` : ''}
-
-
+
+
+
+
+
${album.album_name}
+
${album.artist_name}
+ ${album.release_date ? `
${album.release_date}
` : ''}
+
+
';
- data.tracks.forEach((track, index) => {
- const coverUrl = track.album_cover_url || '/static/placeholder-album.png';
- const durationMin = Math.floor(track.duration_ms / 60000);
- const durationSec = Math.floor((track.duration_ms % 60000) / 1000);
- const duration = `${durationMin}:${durationSec.toString().padStart(2, '0')}`;
+ if (playlistTitle) {
+ playlistTitle.textContent = `${seasonData.icon} ${seasonData.name} Mix`;
+ }
+ if (playlistSubtitle) {
+ playlistSubtitle.textContent = `Curated playlist for ${seasonData.name.toLowerCase()}`;
+ }
- html += `
-
-
${index + 1}
-
-
-
-
-
${track.track_name}
-
${track.artist_name}
-
-
${track.album_name}
-
${duration}
-
- `;
+ // Re-create the controller when the season key changes so the
+ // fetchUrl always points at the active season's endpoint.
+ if (!_seasonalPlaylistCtrl || _seasonalPlaylistCtrlKey !== currentSeasonKey) {
+ _seasonalPlaylistCtrl = createDiscoverSectionController({
+ id: 'seasonal-playlist',
+ contentEl: '#seasonal-playlist',
+ fetchUrl: `/api/discover/seasonal/${currentSeasonKey}/playlist`,
+ extractItems: (data) => data.tracks || [],
+ renderItems: (items) => {
+ discoverSeasonalTracks = items;
+ const rows = items.map((t, i) => _renderCompactTrackRow(t, i)).join('');
+ return `
${rows}
`;
+ },
+ loadingMessage: 'Loading playlist...',
+ emptyMessage: 'No tracks available yet',
+ errorMessage: 'Failed to load playlist',
+ verboseErrors: true,
+ showErrorToast: true,
});
- html += '
-
-
Fetching and matching artists from your services...
-
+
+
Fetching and matching artists from your services...
+
-