kryten-webqueue 0.5.2__tar.gz → 0.6.1__tar.gz

{kryten_webqueue-0.5.2 → kryten_webqueue-0.6.1}/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.1] - 2026-06-05
+
+### Added
+
+- **Receipt confirmation modal for Queue & Play Next** — Clicking **Queue** or **Play Next** now opens a receipt-style modal before spending. It calls `/queue/preview` and shows the item title, price, any rank discount, total cost, current balance, and balance after the transaction, then asks the user to confirm. Unavailable purchases (insufficient balance, cooldown, daily limit, blackout) disable the confirm button with an explanatory message.
+- **Enriched `/queue/preview` receipt data** — The preview endpoint now returns the catalog `title`, `base_cost`, `discount_amount`, current `balance`, and `balance_after` in addition to the existing cost/discount fields. `base_cost` comes from the economy service when available and is otherwise derived from the discount percentage.
+- **Shared modal styling** — Added CSS for `.modal-overlay`/`.modal-box`/`.modal-actions` (also styling the existing admin queue modal) plus a dedicated receipt table layout.
+
+[0.6.1]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.6.1
+
+## [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

{kryten_webqueue-0.5.2 → kryten_webqueue-0.6.1}/PKG-INFO

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

{kryten_webqueue-0.5.2 → kryten_webqueue-0.6.1}/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.2 → kryten_webqueue-0.6.1}/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.1/kryten_webqueue/jobs/__init__.py

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

kryten_webqueue-0.6.1/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.2 → kryten_webqueue-0.6.1}/kryten_webqueue/queue/ordering.py

@@ -116,7 +116,18 @@ async def insert_pay_queue(
         # 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()
-        target_uid = last_pay_uid if last_pay_uid else await _now_playing_uid(api_gate, shadow)
+        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 (always appended; repositioned below)
         try:
@@ -167,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,
@@ -224,6 +236,13 @@ async def insert_pay_playnext(
 
         # 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:
@@ -274,6 +293,7 @@ async def insert_pay_playnext(
         item = {
             "uid": uid,
             "title": title,
+            "friendly_token": _ft,
             "media_type": media_type,
             "media_id": media_id,
             "duration_sec": duration_sec,
@@ -297,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,
@@ -308,18 +357,39 @@ 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).
+
+    ``mode`` selects how the item is positioned:
 
-    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.
+    - ``"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.
     """
+    if mode == "cancel":
+        return {"success": False, "error": "cancelled", "cancelled": True}
+
     async with _queue_lock:
-        # Target position: immediately after the LAST item in the persistent
-        # pay-queue list, or after the currently-playing item when none exist.
-        # The admin item itself is NOT added to the persistent pay list.
-        last_pay_uid = await db.get_last_pay_uid()
-        target_uid = last_pay_uid if last_pay_uid else await _now_playing_uid(api_gate, shadow)
+        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:
@@ -351,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,
@@ -372,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.2 → kryten_webqueue-0.6.1}/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.2 → kryten_webqueue-0.6.1}/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
+

kryten_webqueue-0.6.1/kryten_webqueue/routes/admin_jobs.py

@@ -0,0 +1,32 @@
+from fastapi import APIRouter, Request, Depends, HTTPException
+
+from ..auth.session import require_admin
+
+router = APIRouter(prefix="/admin/jobs", tags=["admin"])
+
+
+@router.get("")
+async def list_jobs(request: Request, user: dict = Depends(require_admin)):
+    """List registered background jobs and whether each is running."""
+    job_manager = request.app.state.job_manager
+    return job_manager.list_jobs()
+
+
+@router.get("/runs")
+async def job_runs(request: Request, user: dict = Depends(require_admin), job: str | None = None, limit: int = 10):
+    """Recent run history, optionally filtered by job name."""
+    db = request.app.state.db
+    return await db.get_job_runs(job_name=job, limit=limit)
+
+
+@router.post("/{name}/run")
+async def run_job(request: Request, name: str, user: dict = Depends(require_admin)):
+    """Trigger a registered job to run in the background."""
+    job_manager = request.app.state.job_manager
+    try:
+        result = await job_manager.run(name, triggered_by=user["username"])
+    except KeyError:
+        raise HTTPException(404, f"Unknown job: {name}")
+    if not result.get("started"):
+        raise HTTPException(409, result.get("reason", "Job already running"))
+    return {"success": True, **result}

{kryten_webqueue-0.5.2 → kryten_webqueue-0.6.1}/kryten_webqueue/routes/admin_queue.py

@@ -8,11 +8,16 @@ router = APIRouter(prefix="/admin/queue", tags=["admin"])
 
 @router.post("/add")
 async def admin_add(request: Request, user: dict = Depends(require_admin)):
-    """Queue an item as admin: zero cost, first available non-pay slot."""
+    """Queue an item as admin: zero cost, position resolved by `mode`."""
     body = await request.json()
     friendly_token = body.get("friendly_token")
+    mode = body.get("mode", "after_purchased")
     if not friendly_token:
         raise HTTPException(400, "friendly_token required")
+    if mode not in ("after_purchased", "playnext_refund", "cancel"):
+        raise HTTPException(400, "invalid mode")
+    if mode == "cancel":
+        return {"success": False, "cancelled": True}
 
     db = request.app.state.db
     api_gate = request.app.state.api_gate
@@ -36,6 +41,7 @@ async def admin_add(request: Request, user: dict = Depends(require_admin)):
         friendly_token=friendly_token,
         title=item["title"],
         duration_sec=item["duration_sec"],
+        mode=mode,
     )
 
     if not result["success"]:

{kryten_webqueue-0.5.2 → kryten_webqueue-0.6.1}/kryten_webqueue/routes/pages.py

@@ -91,6 +91,23 @@ async def queue_page(request: Request):
     return templates.TemplateResponse(request, "queue/index.html", {"user": user})
 
 
+@router.get("/catalog/item/{friendly_token}", response_class=HTMLResponse)
+async def catalog_item_page(request: Request, friendly_token: str):
+    user = _get_user_or_none(request)
+    if not user:
+        return RedirectResponse("/auth/login")
+    db = request.app.state.db
+    item = await db.get_item_admin(friendly_token)
+    if not item:
+        return templates.TemplateResponse(
+            request, "catalog/item_not_found.html", {"user": user}, status_code=404
+        )
+    return templates.TemplateResponse(request, "catalog/item_detail.html", {
+        "user": user,
+        "item": item,
+    })
+
+
 @router.get("/user/dashboard", response_class=HTMLResponse)
 async def user_dashboard_page(request: Request):
     user = _get_user_or_none(request)

{kryten_webqueue-0.5.2 → kryten_webqueue-0.6.1}/kryten_webqueue/routes/queue.py

@@ -10,7 +10,8 @@ router = APIRouter(prefix="/queue", tags=["queue"])
 async def get_queue_state(request: Request, user: dict = Depends(get_current_user)):
     """Get current queue state."""
     shadow = request.app.state.shadow
-    return shadow.get_queue_state()
+    db = request.app.state.db
+    return await shadow.get_enriched_state(db)
 
 
 @router.post("/add")
@@ -128,7 +129,12 @@ async def play_next(request: Request, user: dict = Depends(get_current_user)):
 @router.get("/preview")
 async def cost_preview(request: Request, friendly_token: str, tier: str = "queue",
                        user: dict = Depends(get_current_user)):
-    """Preview cost for queuing an item."""
+    """Preview the cost of queuing an item as a confirmation receipt.
+
+    Returns the catalog title, pricing breakdown (base cost, discount, total)
+    and the user's balance before/after the transaction so the UI can show a
+    receipt before the user confirms.
+    """
     db = request.app.state.db
     api_gate = request.app.state.api_gate
 
@@ -141,7 +147,38 @@ async def cost_preview(request: Request, friendly_token: str, tier: str = "queue
         duration_sec=item["duration_sec"],
         tier=tier,
     )
-    return preview
+
+    cost_z = preview.get("cost_z")
+    discount_pct = preview.get("discount_pct", 0) or 0
+    # base_cost is provided by newer economy builds; derive it as a fallback.
+    base_cost = preview.get("base_cost")
+    if base_cost is None and cost_z is not None:
+        if discount_pct and discount_pct < 100:
+            base_cost = round(cost_z / (1 - discount_pct / 100))
+        else:
+            base_cost = cost_z
+    discount_amount = (base_cost - cost_z) if (base_cost is not None and cost_z is not None) else 0
+
+    balance = None
+    try:
+        bal = await api_gate.get_balance(user["username"])
+        balance = bal.get("balance")
+    except Exception:
+        balance = None
+
+    balance_after = (balance - cost_z) if (balance is not None and cost_z is not None) else None
+
+    return {
+        **preview,
+        "friendly_token": friendly_token,
+        "title": item["title"],
+        "duration_sec": item["duration_sec"],
+        "tier": tier,
+        "base_cost": base_cost,
+        "discount_amount": discount_amount,
+        "balance": balance,
+        "balance_after": balance_after,
+    }
 
 
 @router.get("/history")