kryten-webqueue 0.5.1__tar.gz → 0.6.0__tar.gz

{kryten_webqueue-0.5.1 → kryten_webqueue-0.6.0}/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-06-05
+
+### Added
+
+- **Item detail page** — Clicking a tile's cover art or title now opens `/catalog/item/{friendly_token}`, a dedicated view showing the cover art, full MediaCMS description, duration, and the same action buttons as the tile (Queue, Play Next, and Queue as Admin for admins). Unknown tokens render a 404 "Item not found" page.
+- **Queue page metadata & reorder handle** — Up-next and now-playing items are now enriched with catalog metadata (cover-art thumbnail, correct title, duration) by matching on `friendly_token` or `manifest_url`. Each queue row gains a drag handle affordance, cover thumbnail, paid-by/tier badges, and a correct ETA. Enrichment is applied to both the `/queue/state` response and the WebSocket broadcast.
+- **Generic background job runner** — New `JobManager` runs registered async jobs as background tasks and records each run (start, end, status, detail) to a new `job_runs` table. The Admin page lists registered jobs with **Run** buttons and shows a recent-run history table styled like the catalog sync log. Catalog Sync is now wired through this framework.
+- **Admin job routes** — `GET /admin/jobs`, `GET /admin/jobs/runs`, and `POST /admin/jobs/{name}/run`.
+
+### Changed
+
+- **Top-bar rebrand to "Channel-Z"** — The navigation brand and page-title suffix now read "Channel-Z" instead of "DropSugar Queue"/"DropSugar".
+- **Footer credit links to GitHub** — "kryten-webqueue" in the footer now links to the project's GitHub repository.
+- **All admin time displays are human-readable and timezone-aware** — Sync-log and job-run timestamps are rendered in the browser's local timezone via shared `formatLocalDateTime`/`formatLocalTime` helpers.
+
+### Fixed
+
+- **Empty now-playing UID is handled safely** — When the robot KV is uninitialised and the now-playing UID is unavailable, Queue and Play Next purchases are cancelled and refunded instead of landing in an undefined position.
+- **Admin "Queue as Admin" position prompt** — Admins are now prompted to resolve the inserted item's position: *Play next & refund pending* (refunds money and removes pending paid items from the queue), *Play after all purchased items*, or *Cancel*.
+
+[0.6.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.6.0
+
+## [0.5.2] - 2026-06-05
+
+### Fixed
+
+- **Queue items now land in the correct playlist position** — Positioning is computed relative to the currently-playing item and the persistent pay-queue list (`queue_shadow` rows with `is_pay = 1`):
+  - **Play Next** — moved to immediately *after* the currently-playing item (previously `prepend`, which placed it before the active item). Existing pay items shift down one position.
+  - **Queue** — moved to immediately after the *last* item in the persistent pay-queue list, or after the currently-playing item when no pay items exist (previously left at the end of the playlist when the pay list was empty).
+  - **Queue as Admin** — same target as Queue, but the item is *not* added to the persistent pay list (`is_pay = 0`).
+  - All paths now add to CyTube with `position="end"` and then issue a single `move` to the resolved target UID, refunding (where applicable) and removing the orphaned item if the move fails.
+
+[0.5.2]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.5.2
+
 ## [0.5.1] - 2026-06-05
 
 ### Added

{kryten_webqueue-0.5.1 → kryten_webqueue-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kryten-webqueue
-Version: 0.5.1
+Version: 0.6.0
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

{kryten_webqueue-0.5.1 → kryten_webqueue-0.6.0}/kryten_webqueue/app.py

@@ -12,6 +12,7 @@ from .config import Config
 from .catalog.db import Database
 from .api_gate.client import ApiGateClient
 from .catalog.sync import CatalogSync
+from .jobs import JobManager
 from .catalog.images import CoverArtResolver
 from .queue.shadow import QueueShadow
 from .queue.poller import StatePoller
@@ -26,6 +27,7 @@ from .routes.user import router as user_router
 from .routes.admin_playlists import router as admin_playlists_router
 from .routes.admin_schedules import router as admin_schedules_router
 from .routes.admin_queue import router as admin_queue_router
+from .routes.admin_jobs import router as admin_jobs_router
 from .routes.pages import router as pages_router
 from .ws.handler import router as ws_router
 
@@ -64,6 +66,15 @@ async def lifespan(app: FastAPI):
     )
     app.state.catalog_sync = catalog_sync
 
+    # Generic background job runner (records run history to job_runs)
+    job_manager = JobManager(db)
+    job_manager.register(
+        "catalog_sync",
+        catalog_sync.sync,
+        label="Catalog Sync",
+    )
+    app.state.job_manager = job_manager
+
     # WebSocket manager
     ws_manager = WebSocketManager()
     app.state.ws_manager = ws_manager
@@ -78,6 +89,7 @@ async def lifespan(app: FastAPI):
         api_gate=api_gate,
         shadow=shadow,
         ws_manager=ws_manager,
+        db=db,
         interval=config.state_poll_interval_sec,
     )
     await poller.start()
@@ -171,6 +183,7 @@ def create_app(config: Config) -> FastAPI:
     app.include_router(admin_playlists_router)
     app.include_router(admin_schedules_router)
     app.include_router(admin_queue_router)
+    app.include_router(admin_jobs_router)
     app.include_router(ws_router)
 
     # Health check

{kryten_webqueue-0.5.1 → kryten_webqueue-0.6.0}/kryten_webqueue/catalog/db.py

@@ -169,6 +169,19 @@ MIGRATIONS = [
     """
     UPDATE catalog SET cover_art_path = NULL, cover_art_source = NULL;
     """,
+    # v4: Generic background job run history
+    """
+    CREATE TABLE IF NOT EXISTS job_runs (
+        id          INTEGER PRIMARY KEY AUTOINCREMENT,
+        job_name    TEXT NOT NULL,
+        started_at  TIMESTAMP NOT NULL,
+        ended_at    TIMESTAMP,
+        status      TEXT NOT NULL DEFAULT 'running',
+        detail      TEXT,
+        triggered_by TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_job_runs_name ON job_runs(job_name, started_at);
+    """,
 ]
 
 
@@ -316,6 +329,29 @@ class Database:
     async def get_item_admin(self, friendly_token: str) -> dict | None:
         return await self._fetch_one("SELECT * FROM catalog WHERE friendly_token = ?", [friendly_token])
 
+    async def get_catalog_brief(self, tokens: list[str], manifest_urls: list[str]) -> dict[str, dict]:
+        """Return a lookup of catalog metadata keyed by BOTH friendly_token and
+        manifest_url, for enriching queue-shadow items that may only carry one.
+        """
+        keys = [k for k in ({*tokens} | {*manifest_urls}) if k]
+        if not keys:
+            return {}
+        placeholders = ",".join("?" * len(keys))
+        rows = await self._fetch_all(
+            "SELECT friendly_token, manifest_url, title, duration_sec, "
+            "cover_art_path, thumbnail_url FROM catalog "
+            f"WHERE friendly_token IN ({placeholders}) OR manifest_url IN ({placeholders})",
+            keys + keys,
+        )
+        lookup: dict[str, dict] = {}
+        for row in rows:
+            data = dict(row)
+            if data.get("friendly_token"):
+                lookup[data["friendly_token"]] = data
+            if data.get("manifest_url"):
+                lookup[data["manifest_url"]] = data
+        return lookup
+
     async def is_restricted(self, friendly_token: str) -> bool:
         sql = """
             SELECT 1 FROM saved_playlist_items spi
@@ -393,6 +429,33 @@ class Database:
             "SELECT * FROM sync_log ORDER BY id DESC LIMIT ?", [limit]
         )
 
+    # --- Generic job runs ---
+
+    async def start_job_run(self, job_name: str, triggered_by: str | None = None) -> int:
+        cursor = await self._db.execute(
+            "INSERT INTO job_runs (job_name, started_at, status, triggered_by) "
+            "VALUES (?, ?, 'running', ?)",
+            [job_name, datetime.now(UTC).isoformat(), triggered_by],
+        )
+        await self._db.commit()
+        return cursor.lastrowid
+
+    async def finish_job_run(self, run_id: int, status: str, detail: str | None = None):
+        await self._execute(
+            "UPDATE job_runs SET ended_at=?, status=?, detail=? WHERE id=?",
+            [datetime.now(UTC).isoformat(), status, detail, run_id],
+        )
+
+    async def get_job_runs(self, job_name: str | None = None, limit: int = 10) -> list[dict]:
+        if job_name:
+            return await self._fetch_all(
+                "SELECT * FROM job_runs WHERE job_name=? ORDER BY id DESC LIMIT ?",
+                [job_name, limit],
+            )
+        return await self._fetch_all(
+            "SELECT * FROM job_runs ORDER BY id DESC LIMIT ?", [limit]
+        )
+
     # --- OTP ---
 
     async def store_otp(self, username: str, code: str, expires_at: str):

kryten_webqueue-0.6.0/kryten_webqueue/jobs/__init__.py

@@ -0,0 +1,3 @@
+from .manager import JobManager
+
+__all__ = ["JobManager"]

kryten_webqueue-0.6.0/kryten_webqueue/jobs/manager.py

@@ -0,0 +1,70 @@
+"""Generic background job runner with run-history tracking.
+
+Registers named async job functions and runs them as background tasks,
+recording each run (start, end, status, detail) to the ``job_runs`` table
+so the admin UI can display recent history — the same pattern used for
+catalog sync.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Awaitable, Callable
+
+logger = logging.getLogger(__name__)
+
+# A job is an async callable returning an optional dict of result detail.
+JobFunc = Callable[[], Awaitable[dict | None]]
+
+
+class JobManager:
+    def __init__(self, db):
+        self._db = db
+        self._jobs: dict[str, dict] = {}
+        self._running: dict[str, asyncio.Task] = {}
+
+    def register(self, name: str, func: JobFunc, *, label: str | None = None):
+        """Register a named job."""
+        self._jobs[name] = {"func": func, "label": label or name}
+
+    def list_jobs(self) -> list[dict]:
+        return [
+            {"name": name, "label": meta["label"], "running": name in self._running}
+            for name, meta in self._jobs.items()
+        ]
+
+    def is_running(self, name: str) -> bool:
+        return name in self._running
+
+    async def run(self, name: str, *, triggered_by: str | None = None) -> dict:
+        """Start a job in the background. Returns immediately.
+
+        Raises KeyError if the job is unknown; returns ``already_running``
+        status if a run is in progress.
+        """
+        if name not in self._jobs:
+            raise KeyError(name)
+        if name in self._running:
+            return {"started": False, "reason": "already_running"}
+
+        run_id = await self._db.start_job_run(name, triggered_by=triggered_by)
+        task = asyncio.create_task(self._execute(name, run_id))
+        self._running[name] = task
+        return {"started": True, "run_id": run_id}
+
+    async def _execute(self, name: str, run_id: int):
+        func = self._jobs[name]["func"]
+        try:
+            result = await func()
+            detail = json.dumps(result) if result is not None else None
+            await self._db.finish_job_run(run_id, "completed", detail)
+        except asyncio.CancelledError:
+            await self._db.finish_job_run(run_id, "cancelled", None)
+            raise
+        except Exception as exc:  # noqa: BLE001 - record any failure
+            logger.exception("Job '%s' failed", name)
+            await self._db.finish_job_run(
+                run_id, "failed", json.dumps({"error": f"{type(exc).__name__}: {exc}"})
+            )
+        finally:
+            self._running.pop(name, None)

{kryten_webqueue-0.5.1 → kryten_webqueue-0.6.0}/kryten_webqueue/queue/ordering.py

@@ -50,6 +50,39 @@ async def _announce_queued(api_gate, shadow, *, uid: int, title: str, username:
         logger.warning("Failed to send queue announcement", exc_info=True)
 
 
+async def _now_playing_uid(api_gate, shadow) -> int | None:
+    """UID of the currently-playing item, preferring fresh state over the cache."""
+    np = None
+    try:
+        np = await api_gate.get_now_playing()
+    except Exception:
+        np = None
+    if not np:
+        np = shadow.now_playing
+    if not np:
+        return None
+    uid = np.get("uid")
+    try:
+        return int(uid) if uid is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _shadow_index_after_uid(shadow, target_uid: int | None) -> int:
+    """Shadow list index immediately after target_uid (end of list if not found)."""
+    if target_uid is not None:
+        for idx, it in enumerate(shadow.items):
+            if it.get("uid") == target_uid:
+                return idx + 1
+    return len(shadow.items)
+
+
+async def _move_after(api_gate, *, uid: int, target_uid: int | None) -> None:
+    """Move uid to immediately after target_uid. No-op when target is None."""
+    if target_uid is not None:
+        await api_gate.playlist_move(uid, target_uid)
+
+
 async def insert_pay_queue(
     *,
     api_gate,
@@ -80,16 +113,28 @@ async def insert_pay_queue(
         except httpx.HTTPStatusError as exc:
             return {"success": False, "error": f"Spend failed: {exc.response.status_code}"}
 
-        # Find position: after last pay item, or prepend if none
+        # Target position: immediately after the LAST item in the persistent
+        # pay-queue list, or after the currently-playing item when none exist.
         last_pay_uid = await db.get_last_pay_uid()
-        position = "end" if not last_pay_uid else str(last_pay_uid)
+        if last_pay_uid:
+            target_uid = last_pay_uid
+        else:
+            target_uid = await _now_playing_uid(api_gate, shadow)
+            if target_uid is None:
+                # No anchor to position against (robot KV not initialised).
+                # Cancel and refund rather than dumping the item at the end.
+                try:
+                    await api_gate.queue_refund(username=username, request_id=request_id, reason="no_now_playing")
+                except Exception:
+                    pass
+                return {"success": False, "error": "Queue position unavailable (now-playing unknown); refunded"}
 
-        # Add to CyTube playlist
+        # Add to CyTube playlist (always appended; repositioned below)
         try:
             add_result = await api_gate.playlist_add(
                 media_type=media_type,
                 media_id=media_id,
-                position=position,
+                position="end",
             )
         except httpx.HTTPStatusError as exc:
             try:
@@ -107,20 +152,19 @@ async def insert_pay_queue(
 
         uid = add_result["uid"]
 
-        # Move after last pay UID if needed; refund + remove if positioning fails
-        if last_pay_uid:
+        # Move after the target UID; refund + remove if positioning fails
+        try:
+            await _move_after(api_gate, uid=uid, target_uid=target_uid)
+        except httpx.HTTPStatusError:
             try:
-                await api_gate.playlist_move(uid, last_pay_uid)
-            except httpx.HTTPStatusError:
-                try:
-                    await api_gate.queue_refund(username=username, request_id=request_id, reason="move_failed")
-                except Exception:
-                    pass
-                try:
-                    await api_gate.playlist_delete(uid)
-                except Exception:
-                    pass
-                return {"success": False, "error": "Failed to position item in queue"}
+                await api_gate.queue_refund(username=username, request_id=request_id, reason="move_failed")
+            except Exception:
+                pass
+            try:
+                await api_gate.playlist_delete(uid)
+            except Exception:
+                pass
+            return {"success": False, "error": "Failed to position item in queue"}
 
         # Record spend
         _ft = friendly_token if friendly_token is not None else (media_id if media_type == "cm" else None)
@@ -134,6 +178,7 @@ async def insert_pay_queue(
         item = {
             "uid": uid,
             "title": title,
+            "friendly_token": _ft,
             "media_type": media_type,
             "media_id": media_id,
             "duration_sec": duration_sec,
@@ -143,11 +188,8 @@ async def insert_pay_queue(
             "z_cost": z_cost,
             "schedule_id": None,
         }
-        # Position after last pay
-        if last_pay_uid:
-            pos = await db.get_shadow_position_after(last_pay_uid)
-        else:
-            pos = len(shadow.items)
+        # Position immediately after the target UID
+        pos = _shadow_index_after_uid(shadow, target_uid)
         await shadow.insert_at(item, pos)
 
         # Queue history
@@ -192,7 +234,17 @@ async def insert_pay_playnext(
         except httpx.HTTPStatusError as exc:
             return {"success": False, "error": f"Spend failed: {exc.response.status_code}"}
 
-        # Add to CyTube playlist at prepend position
+        # Target position: immediately after the currently-playing item.
+        target_uid = await _now_playing_uid(api_gate, shadow)
+        if target_uid is None:
+            # Cannot place "play next" without knowing the active item.
+            try:
+                await api_gate.queue_refund(username=username, request_id=request_id, reason="no_now_playing")
+            except Exception:
+                pass
+            return {"success": False, "error": "Play-next unavailable (now-playing unknown); refunded"}
+
+        # Add to CyTube playlist (always appended; repositioned below)
         try:
             add_result = await api_gate.playlist_add(
                 media_type=media_type,
@@ -214,9 +266,9 @@ async def insert_pay_playnext(
 
         uid = add_result["uid"]
 
-        # Move to front; refund + remove if positioning fails
+        # Move to immediately after the now-playing item; refund + remove on failure
         try:
-            await api_gate.playlist_move(uid, "prepend")
+            await _move_after(api_gate, uid=uid, target_uid=target_uid)
         except httpx.HTTPStatusError:
             try:
                 await api_gate.queue_refund(username=username, request_id=request_id, reason="move_failed")
@@ -236,10 +288,12 @@ async def insert_pay_playnext(
             tier=tier, z_cost=z_cost,
         )
 
-        # Update local shadow at position 0
+        # Update local shadow immediately after now-playing. Existing pay items
+        # shift down one position as insert_at re-indexes the list.
         item = {
             "uid": uid,
             "title": title,
+            "friendly_token": _ft,
             "media_type": media_type,
             "media_id": media_id,
             "duration_sec": duration_sec,
@@ -249,7 +303,8 @@ async def insert_pay_playnext(
             "z_cost": z_cost,
             "schedule_id": None,
         }
-        await shadow.insert_at(item, 0)
+        pos = _shadow_index_after_uid(shadow, target_uid)
+        await shadow.insert_at(item, pos)
 
         await db.add_queue_history(
             username=username, friendly_token=_ft,
@@ -262,6 +317,35 @@ async def insert_pay_playnext(
         return {"success": True, "uid": uid, "request_id": request_id}
 
 
+async def _refund_and_remove_pending_pay(api_gate, shadow, db) -> int:
+    """Refund and remove every pending (up-next) paid item from the queue.
+
+    Returns the number of items removed. The currently-playing item is never
+    touched (it is not present in the pay shadow as an up-next item).
+    """
+    pending = await db.get_pay_items()
+    np_uid = await _now_playing_uid(api_gate, shadow)
+    removed = 0
+    for it in pending:
+        uid = it.get("uid")
+        if uid is None or uid == np_uid:
+            continue
+        try:
+            await refund_item(api_gate=api_gate, db=db, uid=uid, reason="admin_playnext_refund")
+        except Exception:
+            logger.warning("Refund failed for uid %s during admin override", uid, exc_info=True)
+        try:
+            await api_gate.playlist_delete(uid)
+        except Exception:
+            logger.warning("Delete failed for uid %s during admin override", uid, exc_info=True)
+        try:
+            await shadow.remove(uid)
+        except Exception:
+            pass
+        removed += 1
+    return removed
+
+
 async def insert_admin_queue(
     *,
     api_gate,
@@ -273,23 +357,46 @@ async def insert_admin_queue(
     friendly_token: str | None = None,
     title: str,
     duration_sec: int,
+    mode: str = "after_purchased",
 ) -> dict:
-    """Insert a zero-cost admin item in the first available non-pay slot.
+    """Insert a zero-cost admin item (no economy interaction).
 
-    Treated exactly like a non-paid item (no economy interaction). It is placed
-    immediately after the last paid item, i.e. at the top of the free section.
+    ``mode`` selects how the item is positioned:
+
+    - ``"after_purchased"`` (default): placed immediately after the last item in
+      the persistent pay-queue list, i.e. at the top of the free section.
+    - ``"playnext_refund"``: every pending (up-next) paid item is refunded and
+      removed, then the admin item is placed immediately after the now-playing
+      item.
+    - ``"cancel"``: no-op.
     """
-    async with _queue_lock:
-        # First available non-pay slot is right after the last pay item.
-        last_pay_uid = await db.get_last_pay_uid()
-        position = "end" if not last_pay_uid else str(last_pay_uid)
+    if mode == "cancel":
+        return {"success": False, "error": "cancelled", "cancelled": True}
 
-        # Add to CyTube playlist
+    async with _queue_lock:
+        if mode == "playnext_refund":
+            removed = await _refund_and_remove_pending_pay(api_gate, shadow, db)
+            target_uid = await _now_playing_uid(api_gate, shadow)
+            if target_uid is None:
+                return {"success": False, "error": "Play-next unavailable (now-playing unknown)"}
+        else:
+            # after_purchased: immediately after the LAST persistent pay item,
+            # or after the currently-playing item when none exist.
+            removed = 0
+            last_pay_uid = await db.get_last_pay_uid()
+            if last_pay_uid:
+                target_uid = last_pay_uid
+            else:
+                target_uid = await _now_playing_uid(api_gate, shadow)
+                if target_uid is None:
+                    return {"success": False, "error": "Queue position unavailable (now-playing unknown)"}
+
+        # Add to CyTube playlist (always appended; repositioned below)
         try:
             add_result = await api_gate.playlist_add(
                 media_type=media_type,
                 media_id=media_id,
-                position=position,
+                position="end",
             )
         except httpx.HTTPStatusError as exc:
             return {"success": False, "error": _add_failure_reason(None, exc)}
@@ -298,16 +405,15 @@ async def insert_admin_queue(
 
         uid = add_result["uid"]
 
-        # Move to the top of the free section if there are pay items above
-        if last_pay_uid:
+        # Move after the target UID; remove the orphan if positioning fails
+        try:
+            await _move_after(api_gate, uid=uid, target_uid=target_uid)
+        except httpx.HTTPStatusError:
             try:
-                await api_gate.playlist_move(uid, last_pay_uid)
-            except httpx.HTTPStatusError:
-                try:
-                    await api_gate.playlist_delete(uid)
-                except Exception:
-                    pass
-                return {"success": False, "error": "Failed to position item in queue"}
+                await api_gate.playlist_delete(uid)
+            except Exception:
+                pass
+            return {"success": False, "error": "Failed to position item in queue"}
 
         _ft = friendly_token if friendly_token is not None else (media_id if media_type == "cm" else None)
 
@@ -315,6 +421,7 @@ async def insert_admin_queue(
         item = {
             "uid": uid,
             "title": title,
+            "friendly_token": _ft,
             "media_type": media_type,
             "media_id": media_id,
             "duration_sec": duration_sec,
@@ -324,10 +431,7 @@ async def insert_admin_queue(
             "z_cost": None,
             "schedule_id": None,
         }
-        if last_pay_uid:
-            pos = await db.get_shadow_position_after(last_pay_uid)
-        else:
-            pos = len(shadow.items)
+        pos = _shadow_index_after_uid(shadow, target_uid)
         await shadow.insert_at(item, pos)
 
         # Queue history (zero cost, admin tier)
@@ -339,7 +443,8 @@ async def insert_admin_queue(
         # Announce placement to the channel
         await _announce_queued(api_gate, shadow, uid=uid, title=title, username=username)
 
-        return {"success": True, "uid": uid}
+        return {"success": True, "uid": uid, "refunded": removed}
+
 
 
 async def refund_item(*, api_gate, db, uid: int, reason: str) -> bool:

{kryten_webqueue-0.5.1 → kryten_webqueue-0.6.0}/kryten_webqueue/queue/poller.py

@@ -7,10 +7,11 @@ logger = logging.getLogger(__name__)
 class StatePoller:
     """Polls api-gate at a fixed interval to keep QueueShadow in sync."""
 
-    def __init__(self, *, api_gate, shadow, ws_manager, interval: float = 3.0):
+    def __init__(self, *, api_gate, shadow, ws_manager, db=None, interval: float = 3.0):
         self._api_gate = api_gate
         self._shadow = shadow
         self._ws_manager = ws_manager
+        self._db = db
         self._interval = interval
         self._task: asyncio.Task | None = None
 
@@ -34,7 +35,10 @@ class StatePoller:
                 now_playing = await self._api_gate.get_now_playing()
                 await self._shadow.apply_poll_result(playlist, now_playing)
                 # Broadcast updated state
-                state = self._shadow.get_queue_state()
+                if self._db is not None:
+                    state = await self._shadow.get_enriched_state(self._db)
+                else:
+                    state = self._shadow.get_queue_state()
                 await self._ws_manager.broadcast({"type": "queue_state", "data": state})
             except asyncio.CancelledError:
                 raise

{kryten_webqueue-0.5.1 → kryten_webqueue-0.6.0}/kryten_webqueue/queue/shadow.py

@@ -132,3 +132,57 @@ class QueueShadow:
             "now_playing": self._now_playing,
             "updated_at": datetime.now(UTC).isoformat(),
         }
+
+    async def get_enriched_state(self, db) -> dict:
+        """Queue state augmented with catalog metadata (cover art, etc.)."""
+        state = self.get_queue_state()
+        items = state.get("items") or []
+        now_playing = state.get("now_playing")
+
+        tokens, manifests = [], []
+        for it in items:
+            if it.get("friendly_token"):
+                tokens.append(it["friendly_token"])
+            if it.get("media_id"):
+                manifests.append(it["media_id"])
+        if now_playing:
+            if now_playing.get("friendly_token"):
+                tokens.append(now_playing["friendly_token"])
+            if now_playing.get("id"):
+                manifests.append(now_playing["id"])
+
+        try:
+            lookup = await db.get_catalog_brief(tokens, manifests)
+        except Exception:
+            logger.warning("Failed to enrich queue state with catalog metadata", exc_info=True)
+            return state
+
+        def _meta_for(obj: dict, id_key: str) -> dict | None:
+            return lookup.get(obj.get("friendly_token") or "") or lookup.get(obj.get(id_key) or "")
+
+        enriched_items = []
+        for it in items:
+            meta = _meta_for(it, "media_id")
+            merged = dict(it)
+            if meta:
+                merged.setdefault("cover_art_path", meta.get("cover_art_path"))
+                merged.setdefault("thumbnail_url", meta.get("thumbnail_url"))
+                if not merged.get("title") or merged.get("title") == "Unknown":
+                    merged["title"] = meta.get("title") or merged.get("title")
+                if not merged.get("friendly_token"):
+                    merged["friendly_token"] = meta.get("friendly_token")
+            enriched_items.append(merged)
+        state["items"] = enriched_items
+
+        if now_playing:
+            meta = _meta_for(now_playing, "id")
+            np = dict(now_playing)
+            if meta:
+                np.setdefault("cover_art_path", meta.get("cover_art_path"))
+                np.setdefault("thumbnail_url", meta.get("thumbnail_url"))
+                if not np.get("friendly_token"):
+                    np["friendly_token"] = meta.get("friendly_token")
+            state["now_playing"] = np
+
+        return state
+