kryten-webqueue 0.15.2__tar.gz → 0.17.0__tar.gz

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/CHANGELOG.md

@@ -6,6 +6,27 @@ 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).
 ## [Unreleased]
 
+## [0.17.0] — 2026-06-17
+
+### Added
+
+- **Search now combines with category/tag filters.** A free-text search ANDs with the selected category and/or tag instead of ignoring them. `db.search()` / `db.search_count()` accept `category` and `tag`; the `/catalog/search` page and JSON route pass them through and keep the dropdowns populated/selected; `applyFacets()` includes the active facets when a query is present. (Shared `_facet_filter()` SQL helper keeps browse and search behavior identical.)
+- **Clear empty-results messaging.** When a search and/or facet filter returns nothing, the catalog page now explains *why* — naming the active query and filters — and offers one-click escapes ("Search without filters", "Clear filters", "Back to browse") instead of a bare "No items found."
+
+[0.17.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.17.0
+
+## [0.16.0] — 2026-06-17
+
+### Added
+
+- **Light / dark theme toggle.** A navbar button switches between dark (default) and light themes. The choice persists in `localStorage`; first-time visitors follow their OS `prefers-color-scheme`. An inline pre-paint script in `base.html` applies the saved/preferred theme before first render to avoid a flash. Light/dark palettes are defined as `:root[data-theme="..."]` overrides of the existing CSS variables, so the whole UI re-themes without per-component changes.
+
+### Changed
+
+- **Clearer playlist terminology (display only).** Admin playlist/schedule/promo screens now label reserved playlists as **Non-preemptable** and normal ones as **Preemptable** (previously "Immutable" / "Mutable"). This is a wording change only — the `is_immutable` data field, API payloads, and config keys are unchanged.
+
+[0.16.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.16.0
+
 ## [0.15.2] — 2026-06-17
 
 ### Fixed

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/PKG-INFO

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

kryten_webqueue-0.17.0/docs/UX_POLISH_PLAN.md

@@ -0,0 +1,246 @@
+# kryten-webqueue — UX Polish & Convenience Plan
+
+Status: **proposed (awaiting approval)**. No application code changed yet.
+
+This plan covers seven UX/convenience items. Each can ship independently; grouped
+into phases so each phase is independently verifiable and releasable.
+
+Scope note: display-only relabeling and front-end live-refresh are deliberately
+kept separate from data-model/API changes so nothing downstream (api-gate,
+economy, DB schema) needs to move in lock-step.
+
+---
+
+## Item 1 — Active event shows as "active" long after it ended
+
+**Root cause.** The `active_schedule` row (single row, `id=1`) is only removed by
+the admin "Clear Active Schedule" button (`clear_active_schedule()` →
+`DELETE FROM active_schedule`). The in-progress *lock* auto-lifts
+(`disable_active_lock()` sets `lock_disabled=1` when the last scheduled item
+begins), but the **row itself persists**, so the admin banner keeps showing the
+event. `estimated_end_at` is computed once at fire time and never enforced.
+
+Relevant code:
+- `catalog/db.py` — `set_active_schedule()`, `get_active_schedule()`,
+  `clear_active_schedule()`, `disable_active_lock()`, `is_event_lock_active()`,
+  and `active_schedule` schema (`last_item_uid`, `lock_disabled`, `estimated_end_at`).
+- `queue/shadow.py` — `_maybe_lift_event_lock()` already detects when the last
+  scheduled item is playing (event effectively over).
+- `templates/admin/schedules.html` — `loadActive()` renders the banner once.
+
+**Fix (event-driven primary + safety net).**
+1. Backend: when the scheduled event is truly over, clear the active row, don't
+   just lift the lock. Extend the existing `_maybe_lift_event_lock()` logic in
+   `shadow.apply_poll_result()`: once the last scheduled item (`last_item_uid`)
+   has played out (i.e. now-playing has advanced *past* it, or the row is gone
+   from the queue), call a new `db.expire_active_schedule_if_done()` that clears
+   the row. Keeps the existing "lift lock when last item *starts*" behavior, and
+   adds "clear active when last item *ends*".
+2. Backend safety net: in the same path, if `estimated_end_at` is more than a
+   small grace (e.g. 5 min) in the past, clear the active row. Guards against a
+   missed boundary (manual queue edits, restart during an event).
+3. Frontend: `loadActive()` treats a past `estimated_end_at` as "ended" (hide
+   banner) even before the backend clears it, and refreshes (see Item 2).
+
+**Verification.** Fire a short immutable schedule; confirm the banner clears
+shortly after the last item finishes (not on reload). Unit test the new db
+helper: row present → played past last item → row cleared. Test the
+`estimated_end_at` grace path.
+
+---
+
+## Item 2 — Admin page doesn't live-update (queue, now-playing, jobs)
+
+**Root cause.** `templates/admin/index.html` calls `loadAdminData()` /
+`loadJobs()` **once** on load. Unlike `templates/queue/index.html`, it never
+opens the `/ws` WebSocket, so queue size / now-playing / job status only refresh
+on a manual reload. The poller already broadcasts `{"type":"queue_state"}` every
+~3s (`queue/poller.py`).
+
+**Fix.**
+1. Subscribe the admin page to `/ws` (reuse the queue page's connect pattern).
+   On `queue_state`, update the "Queue Status" block (items count + now-playing).
+   On `schedule_fired`, refresh the active-schedule banner + queue status.
+2. Jobs: lightweight `setInterval` (e.g. every 5s) re-fetch of `/admin/jobs` and
+   `/admin/jobs/runs?limit=10` while the tab is visible (pause via
+   `document.visibilityState` to avoid background churn). Jobs are DB-polled, not
+   broadcast, so polling is the pragmatic choice; interval is cheap.
+3. Active schedule banner (shared with Item 1): re-render on the same interval
+   and on `schedule_fired`.
+
+Relevant code:
+- `templates/admin/index.html` — `loadAdminData()`, `loadJobs()`, init at bottom.
+- `templates/queue/index.html` — `connectWebSocket()` reference implementation.
+- `templates/admin/schedules.html` — `loadActive()` (extract/reuse).
+
+**Verification.** Open admin page; queue another item from CyTube → count and
+now-playing update within a few seconds without reload. Run a job → its status
+flips to running then completed live.
+
+---
+
+## Item 3 — Richer logging, especially fetchurls failures
+
+**Current state.** `jobs/manager.py::_execute()` already logs unexpected failures
+with a full traceback (`logger.exception`) and records `{type}: {msg}` to the
+`job_runs.detail`; `JobError` logs a clean WARNING. The integration
+(`integrations/cmsutils/fetchurls.py`) emits progress phases but uses `print()`
+for per-URL/per-section detail, so that detail never reaches the app logger or
+the job record.
+
+Gaps to close:
+- fetchurls per-section results (resolved/failed counts + the failing URLs &
+  Excel row numbers) are not summarized into the logger or `job_runs.detail`.
+- SharePoint download failures wrap into a `RuntimeError` that loses the HTTP
+  status / response snippet.
+- `JobContext.progress()` swallows DB errors at debug only (acceptable, but note).
+- General: the global log format (added in `logging_config.py`) can include
+  `filename:lineno` to make every line more actionable.
+
+**Fix.**
+1. `jobs/tasks.py::fetchurls_job` (and `_import_section_as_playlist`): after the
+   run, log an INFO summary per section (`name: resolved X / failed Y`) and a
+   WARNING listing each failed URL with its row number; fold a compact
+   `failures` array into the returned `result` so it lands in `job_runs.detail`
+   and shows in the admin "Detail" column.
+2. Enrich the SharePoint download error to include HTTP status + a short response
+   excerpt before raising.
+3. `logging_config.py`: extend the default formatter to
+   `%(asctime)s %(levelname)-8s %(name)s %(filename)s:%(lineno)d: %(message)s`
+   (app loggers only; keep uvicorn/access formats lean).
+4. Convert the most useful `print()` lines in the fetchurls integration to
+   `logger.info/warning` (guarded so standalone CLI use still prints).
+
+**Verification.** Run fetchurls with a deliberately bad URL; confirm the admin
+job "Detail" shows the failing URL + row, and the process log has an INFO
+section summary + WARNING per failure with `file:line`.
+
+---
+
+## Item 4 — Search string and category/tag filters don't combine
+
+**Root cause.** Two separate code paths. `db.browse()` ANDs category+tag via
+subqueries; `db.search()` (FTS5 `MATCH`) accepts **no** category/tag. The
+frontend `applyFacets()` drops the facet dropdowns entirely when a query is
+active (`if (CURRENT_QUERY) {...} else { set category/tag }`), and
+`/catalog/search` neither accepts facets nor returns facet lists.
+
+**Fix (recommended: make them AND together).**
+1. `db.search()`: add optional `category` / `tag` params and append the same
+   `AND friendly_token IN (… categories …)` / `AND … IN (… tags …)` subqueries
+   `browse()` already uses (intersection with the FTS match).
+2. `routes/catalog.py::search`: accept `category` & `tag`, pass through, and also
+   return `categories`/`tags` facet lists (like `/browse`) plus `active_category`
+   / `active_tag` so the template can keep selections.
+3. `templates/catalog/browse.html::applyFacets()`: when a query is present,
+   include `category`/`tag` in the search URL instead of discarding them; keep
+   the dropdowns populated and selected on the results page.
+
+Fallback option (if you'd rather not expand search): visually disable the facet
+dropdowns on a search results page with a tooltip ("Clear search to filter by
+category/tag"). Cheaper, but less capable. **Recommendation: do the real fix.**
+
+**Verification.** Search "matrix" + pick a category → results are the
+intersection. Remove the query → browse facets still AND as before. Add a small
+test for `db.search(category=…, tag=…)`.
+
+---
+
+## Item 5 — Rename Mutable/Immutable → Preemptable/Non-preemptable (display only)
+
+**Root cause.** Pure UX wording. The data field `is_immutable` (DB column, API
+body, JS variable) must stay; only visible labels change.
+
+**Fix (display-only).** In `templates/admin/playlists.html`:
+- Badges: "Immutable" → "Non-preemptable"; "Mutable" → "Preemptable" (L~96).
+- Create-modal checkbox label (L~128) and editor metadata text (L~164/170).
+- Confirm dialog copy in `toggleImmutable()` if it references the words.
+- Keep the button verbs ("Reserve"/"Release") as-is (decision 2 default).
+In `templates/admin/schedules.html`: the active-banner "Immutable" badge (L~40)
+→ "Non-preemptable".
+
+Do **not** change: `is_immutable` column, `set_active_schedule(is_immutable=…)`,
+API request/response keys, JS variable names, or config keys.
+
+**Verification.** Grep templates for user-visible "mutable"/"immutable" → none
+remain (data attributes/keys excluded). Page renders new labels; toggle still
+posts `is_immutable`.
+
+---
+
+## Item 6 — Zcoin dashboard: tabbed container + wider account column
+
+**Current.** `templates/user/dashboard.html` is a 3-column grid
+(`balance-card | history-card | transactions-card`), with vanity controls
+crammed into the left balance card.
+
+**Fix.** Two-region layout:
+- **Left (widened) account card:** balance, rank/level, progress, perks. Remove
+  the vanity block from here.
+- **Right (wide) tabbed container** with three tabs, lazy-loaded on first show:
+  1. **Queue History** (existing `loadQueue()` + pager)
+  2. **Recent Transactions** (existing `loadTransactions()` + credit/debit toggle)
+  3. **Vanity Items** (moved here: greeting + chat-color editors, with room to
+     grow to other econ-surfaced properties later)
+
+Implementation:
+- Restructure `dashboard.html`: account card + `.tabs` (buttons) + `.tab-panel`s.
+- Reuse existing JS (`loadAccount`, `loadQueue`, `loadTransactions`, vanity
+  dialogs); add a tiny tab controller that lazy-loads each panel once.
+- `static/css/main.css`: change `.dashboard-grid` to a 2-column layout
+  (e.g. `minmax(280px, 360px) 1fr`), collapse to 1 column under ~900px; add
+  `.tabs`, `.tab-btn.active`, `.tab-panel[hidden]` styles (reuse `--accent`,
+  `--border`, etc.). Mirror the existing `.tx-toggle` styling for consistency.
+
+**Verification.** Dashboard shows account card + tabs; switching tabs loads each
+once; vanity edit/purchase still works from its tab; responsive collapse at
+narrow widths. Existing economy endpoints unchanged.
+
+---
+
+## Item 7 — Light / dark mode
+
+**Foundation.** `static/css/main.css` already drives the entire UI from CSS
+variables on `:root` (`--bg-*`, `--text-*`, `--accent`, `--border`, …). Adding a
+theme is mainly a palette swap + a toggle; no per-component CSS rewrite needed.
+
+**Fix.**
+1. Define a light palette under `:root[data-theme="light"]` (and keep the current
+   dark values as the default `:root`). Tune `--bg-*`, `--text-*`, `--border`,
+   `--shadow`; keep `--accent` family. Add an explicit
+   `:root[data-theme="dark"]` block equal to the defaults so the toggle is
+   symmetric.
+2. Default behavior: respect `prefers-color-scheme` when the user hasn't chosen;
+   persist an explicit choice in `localStorage` (`wq_theme`).
+3. No-FOUC: a tiny inline script in `base.html <head>` sets
+   `document.documentElement.dataset.theme` from `localStorage`/media query
+   **before** CSS paints.
+4. Toggle control in the navbar (`base.html`), wired in `static/js/main.js`:
+   flips `data-theme`, saves to `localStorage`, updates the icon/label.
+   Default: icon-only (🌙/☀️) with `aria-label` (decision 3 default).
+5. Audit a few hard-coded colors (e.g. badge `rgba(...)` backgrounds, toast,
+   modal overlay) for acceptable contrast in light mode; promote any offenders
+   to variables.
+
+**Verification.** Toggle flips instantly with no flash on reload; choice
+persists; fresh visitor matches OS preference; spot-check catalog, queue, admin,
+dashboard (incl. new tabs) and modals/toasts in both themes for contrast.
+
+---
+
+## Suggested phasing (each independently releasable)
+
+- **Phase A (quick wins / low risk):** Item 5 (relabel), Item 7 (theme).
+- **Phase B (admin live + lifecycle):** Item 1 (active-event expiry) + Item 2
+  (admin live-update) — they share the active-schedule banner refresh.
+- **Phase C (catalog):** Item 4 (search × facets).
+- **Phase D (dashboard):** Item 6 (tabs) — self-contained.
+- **Phase E (observability):** Item 3 (logging) — can land anytime; complements
+  the earlier promo observability work.
+
+## Open questions / decisions (defaults chosen)
+1. Item 4: real combine **(recommended, default)** vs. disable-with-tooltip.
+2. Item 5: relabel **nouns only** (default), leave the "Reserve/Release" verbs.
+3. Item 7: navbar toggle **icon-only** (🌙/☀️) with `aria-label` (default).
+4. Versioning: **one minor (e.g. 0.16.0) per phase** as completed (default),
+   vs. batch all into one.

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/catalog/db.py

@@ -59,6 +59,36 @@ def _hidden_exclusion(alias: str = "c") -> tuple[str, list]:
     return sql, [*HIDDEN_CATEGORY_NAMES, *HIDDEN_TAG_NAMES]
 
 
+def _facet_filter(alias: str, category: str | None, tag: str | None) -> tuple[str, list]:
+    """SQL fragment (+ params) AND-filtering by a category slug and/or tag name.
+
+    Each filter is an ``AND friendly_token IN (...)`` subquery on the catalog row
+    under ``alias``; an absent filter contributes nothing. Shared by browse() and
+    search() so the two paths narrow results identically.
+    """
+    sql = ""
+    params: list = []
+    if category:
+        sql += f"""
+            AND {alias}.friendly_token IN (
+                SELECT cc.friendly_token FROM catalog_categories cc
+                JOIN categories cat ON cc.category_id = cat.id
+                WHERE cat.slug = ?
+            )
+        """
+        params.append(category)
+    if tag:
+        sql += f"""
+            AND {alias}.friendly_token IN (
+                SELECT ct.friendly_token FROM catalog_tags ct
+                JOIN tags t ON ct.tag_id = t.id
+                WHERE t.name = ?
+            )
+        """
+        params.append(tag)
+    return sql, params
+
+
 # Default quality-weighted ordering (see browse() for rationale).
 _DEFAULT_ORDER = """
     ORDER BY
@@ -446,7 +476,8 @@ class Database:
         row = await self._fetch_one(query, params)
         return row["cnt"] if row else 0
 
-    async def search(self, query_text: str, *, page: int = 1, per_page: int = 24, show_hidden: bool = False, sort: str = "default") -> list[dict]:
+    async def search(self, query_text: str, *, category: str | None = None, tag: str | None = None,
+                     page: int = 1, per_page: int = 24, show_hidden: bool = False, sort: str = "default") -> list[dict]:
         sql = """
             SELECT c.friendly_token, c.title, c.duration_sec, c.cover_art_path, c.cover_art_source, c.thumbnail_url, c.manifest_url,
                    rank AS relevance
@@ -464,6 +495,11 @@ class Database:
             excl_sql, excl_params = _hidden_exclusion("c")
             sql += excl_sql
             params.extend(excl_params)
+        # Category/tag facets AND with the text match (same subqueries browse()
+        # uses), so a search can be narrowed by the selected facets.
+        facet_sql, facet_params = _facet_filter("c", category, tag)
+        sql += facet_sql
+        params.extend(facet_params)
         # Relevance is the natural default for a text query; other sort keys let
         # the user reorder the matched set explicitly.
         sql += " ORDER BY rank " if (sort or "default") == "default" else _browse_order_clause(sort)
@@ -471,7 +507,8 @@ class Database:
         params.extend([per_page, (page - 1) * per_page])
         return await self._fetch_all(sql, params)
 
-    async def search_count(self, query_text: str, *, show_hidden: bool = False) -> int:
+    async def search_count(self, query_text: str, *, category: str | None = None, tag: str | None = None,
+                           show_hidden: bool = False) -> int:
         sql = """
             SELECT COUNT(*) as cnt
             FROM catalog_fts fts
@@ -488,6 +525,9 @@ class Database:
             excl_sql, excl_params = _hidden_exclusion("c")
             sql += excl_sql
             params.extend(excl_params)
+        facet_sql, facet_params = _facet_filter("c", category, tag)
+        sql += facet_sql
+        params.extend(facet_params)
         row = await self._fetch_one(sql, params)
         return row["cnt"] if row else 0
 

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/routes/catalog.py

@@ -19,15 +19,19 @@ async def browse(request: Request, category: str | None = None, tag: str | None
 
 
 @router.get("/search")
-async def search(request: Request, q: str = "", page: int = 1, show_hidden: int = 0,
+async def search(request: Request, q: str = "", category: str | None = None, tag: str | None = None,
+                 page: int = 1, show_hidden: int = 0,
                  sort: str = "default", user: dict = Depends(get_current_user)):
-    """Full-text search of catalog."""
+    """Full-text search of catalog, optionally narrowed by category/tag."""
     if not q.strip():
         raise HTTPException(400, "Query required")
     db = request.app.state.db
     show_hidden = bool(show_hidden) and (user.get("rank") or 0) >= 3
-    items = await db.search(q, page=page, show_hidden=show_hidden, sort=sort)
-    return {"items": items, "query": q, "page": page, "sort": sort}
+    items = await db.search(q, category=category, tag=tag, page=page, show_hidden=show_hidden, sort=sort)
+    categories = await db.get_categories(show_hidden=show_hidden)
+    tags = await db.get_tags(show_hidden=show_hidden)
+    return {"items": items, "categories": categories, "tags": tags,
+            "query": q, "active_category": category, "active_tag": tag, "page": page, "sort": sort}
 
 
 @router.get("/item/{friendly_token}")

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/routes/pages.py

@@ -107,6 +107,7 @@ async def catalog_browse_page(request: Request, category: str | None = None,
 
 @router.get("/catalog/search", response_class=HTMLResponse)
 async def catalog_search_page(request: Request, q: str = "", page: int = 1,
+                             category: str | None = None, tag: str | None = None,
                              show_hidden: int = 0, sort: str = "default"):
     user = _get_user_or_none(request)
     if not user:
@@ -117,8 +118,8 @@ async def catalog_search_page(request: Request, q: str = "", page: int = 1,
     is_admin = (user.get("rank") or 0) >= 3
     show_hidden = bool(show_hidden) and is_admin
     sort = sort if sort in _VALID_SORTS else "default"
-    items = await db.search(q, page=page, show_hidden=show_hidden, sort=sort)
-    total = await db.search_count(q, show_hidden=show_hidden)
+    items = await db.search(q, category=category, tag=tag, page=page, show_hidden=show_hidden, sort=sort)
+    total = await db.search_count(q, category=category, tag=tag, show_hidden=show_hidden)
     total_pages = max(1, (total + 23) // 24)
     categories = await db.get_categories(show_hidden=show_hidden)
     tags = await db.get_tags(show_hidden=show_hidden)
@@ -130,8 +131,8 @@ async def catalog_search_page(request: Request, q: str = "", page: int = 1,
         "tags": tags,
         "page": page,
         "total_pages": total_pages,
-        "active_category": None,
-        "active_tag": None,
+        "active_category": category,
+        "active_tag": tag,
         "query": q,
         "is_admin": is_admin,
         "show_hidden": show_hidden,

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/static/css/main.css

@@ -1,6 +1,9 @@
 /* kryten-webqueue — Main Stylesheet */
 
 :root {
+    /* Default (dark) palette. An explicit [data-theme="dark"] block below mirrors
+       these so the navbar toggle is symmetric; [data-theme="light"] overrides
+       them. Theme-independent tokens (radius, fonts, nav height) live here. */
     --bg-primary: #0f0f14;
     --bg-secondary: #1a1a24;
     --bg-card: #22222e;
@@ -13,13 +16,48 @@
     --warning: #fdcb6e;
     --danger: #e17055;
     --border: #33334a;
-    --radius: 8px;
     --shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+    --radius: 8px;
     --nav-height: 4rem;
     --font-body: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
     --font-heading: 'Sora', 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
 }
 
+/* Explicit dark theme (mirrors the defaults) — set by the toggle. */
+:root[data-theme="dark"] {
+    --bg-primary: #0f0f14;
+    --bg-secondary: #1a1a24;
+    --bg-card: #22222e;
+    --bg-hover: #2a2a3a;
+    --text-primary: #e8e8f0;
+    --text-secondary: #9090a8;
+    --accent: #6c5ce7;
+    --accent-hover: #7f70f0;
+    --success: #00b894;
+    --warning: #fdcb6e;
+    --danger: #e17055;
+    --border: #33334a;
+    --shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+}
+
+/* Light theme. Same accent family; lighter surfaces, darker text, and slightly
+   deepened semantic colors so they keep contrast on white. */
+:root[data-theme="light"] {
+    --bg-primary: #f3f3f8;
+    --bg-secondary: #e9e9f1;
+    --bg-card: #ffffff;
+    --bg-hover: #e4e4ee;
+    --text-primary: #1b1b26;
+    --text-secondary: #5c5c72;
+    --accent: #6c5ce7;
+    --accent-hover: #5a4bd4;
+    --success: #00997a;
+    --warning: #b9810a;
+    --danger: #c84b30;
+    --border: #d6d6e2;
+    --shadow: 0 4px 12px rgba(20, 20, 40, 0.12);
+}
+
 * {
     margin: 0;
     padding: 0;
@@ -85,6 +123,23 @@ a:hover {
     color: var(--text-primary);
 }
 
+/* Theme toggle (navbar) */
+.theme-toggle {
+    background: transparent;
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    color: var(--text-secondary);
+    cursor: pointer;
+    font-size: 1rem;
+    line-height: 1;
+    padding: 0.3rem 0.5rem;
+    transition: color 0.2s, border-color 0.2s, background 0.2s;
+}
+.theme-toggle:hover {
+    color: var(--text-primary);
+    background: var(--bg-hover);
+}
+
 /* Container */
 .container {
     max-width: 1400px;

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/static/js/main.js

@@ -1,5 +1,32 @@
 /* kryten-webqueue — Main JavaScript */
 
+// --- Theme (light/dark) ---
+// The initial theme is applied pre-paint by an inline script in base.html.
+// Here we keep the toggle button's icon in sync and persist explicit choices.
+function currentTheme() {
+    return document.documentElement.dataset.theme === 'light' ? 'light' : 'dark';
+}
+
+function updateThemeToggle() {
+    const btn = document.getElementById('theme-toggle');
+    if (!btn) return;
+    const dark = currentTheme() === 'dark';
+    // Show the icon for the theme you'd switch TO.
+    btn.textContent = dark ? '\u2600\uFE0F' : '\uD83C\uDF19';
+    btn.setAttribute('aria-label', dark ? 'Switch to light theme' : 'Switch to dark theme');
+    btn.title = btn.getAttribute('aria-label');
+}
+
+function setTheme(theme) {
+    document.documentElement.dataset.theme = theme;
+    try { localStorage.setItem('wq_theme', theme); } catch (e) { /* ignore */ }
+    updateThemeToggle();
+}
+
+function toggleTheme() {
+    setTheme(currentTheme() === 'dark' ? 'light' : 'dark');
+}
+
 // Toast notification system
 function showToast(message, type = 'success') {
     const toast = document.createElement('div');
@@ -15,6 +42,12 @@ function showToast(message, type = 'success') {
 
 // Logout handler
 document.addEventListener('DOMContentLoaded', () => {
+    updateThemeToggle();
+    const themeBtn = document.getElementById('theme-toggle');
+    if (themeBtn) {
+        themeBtn.addEventListener('click', toggleTheme);
+    }
+
     const logoutBtn = document.getElementById('logout-btn');
     if (logoutBtn) {
         logoutBtn.addEventListener('click', async (e) => {

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/templates/admin/playlists.html

@@ -93,7 +93,7 @@ async function loadPlaylists() {
                     ${p.description ? `<div class="muted">${escapeHtml(p.description)}</div>` : ''}</td>
                 <td>${p.promo_type
                     ? `<span class="badge badge-accent" title="Promo pool">Promo: ${escapeHtml(p.promo_type)}</span>`
-                    : (p.is_immutable ? '<span class="badge badge-warn">Immutable</span>' : '<span class="muted">Mutable</span>')}</td>
+                    : (p.is_immutable ? '<span class="badge badge-warn">Non-preemptable</span>' : '<span class="muted">Preemptable</span>')}</td>
                 <td>${escapeHtml(p.created_by || '')}</td>
                 <td class="row-actions">
                     <button class="btn btn-sm" onclick="toggleImmutable(${p.id}, ${p.is_immutable ? 1 : 0}, '${escapeHtml(p.name)}')"
@@ -125,7 +125,7 @@ function showCreateModal() {
         <h3>New Playlist</h3>
         <label class="field"><span>Name</span><input type="text" id="pl-name"></label>
         <label class="field"><span>Description</span><input type="text" id="pl-desc"></label>
-        <label class="check"><input type="checkbox" id="pl-immut"> Immutable (reserve items — hidden from public catalog)</label>
+        <label class="check"><input type="checkbox" id="pl-immut"> Non-preemptable (reserve items — hidden from public catalog)</label>
         <div class="modal-actions">
             <button class="btn btn-secondary" onclick="closeModal()">Cancel</button>
             <button class="btn btn-primary" onclick="createPlaylist()">Create</button>
@@ -167,7 +167,7 @@ async function openEditor(id) {
     }));
     document.getElementById('editor-title').textContent = pl.name;
     document.getElementById('editor-meta').textContent =
-        `${pl.is_immutable ? 'Immutable (reserved) · ' : ''}${pl.description || ''}`;
+        `${pl.is_immutable ? 'Non-preemptable (reserved) · ' : ''}${pl.description || ''}`;
     document.getElementById('list-view').classList.add('hidden');
     document.getElementById('editor-view').classList.remove('hidden');
     document.getElementById('cat-results').innerHTML = '';
@@ -307,7 +307,7 @@ function editMeta() {
     showModal(`
         <h3>Rename Playlist</h3>
         <label class="field"><span>Name</span><input type="text" id="em-name" value="${escapeHtml(document.getElementById('editor-title').textContent)}"></label>
-        <label class="check"><input type="checkbox" id="em-immut" ${editorImmutable ? 'checked' : ''}> Immutable (reserve items)</label>
+        <label class="check"><input type="checkbox" id="em-immut" ${editorImmutable ? 'checked' : ''}> Non-preemptable (reserve items)</label>
         <div class="modal-actions">
             <button class="btn btn-secondary" onclick="closeModal()">Cancel</button>
             <button class="btn btn-primary" onclick="saveMeta()">Save</button>

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/templates/admin/promos.html

@@ -87,17 +87,17 @@ async function loadPools() {
                     ${p.description ? `<div class="muted">${escapeHtml(p.description)}</div>` : ''}</td>
                 <td>${p.promo_type
                     ? `<span class="badge badge-accent">${escapeHtml(typeLabel(p.promo_type))}</span>`
-                    : (p.is_immutable ? '<span class="badge badge-warn">Immutable</span>' : '<span class="muted">Mutable</span>')}</td>
+                    : (p.is_immutable ? '<span class="badge badge-warn">Non-preemptable</span>' : '<span class="muted">Preemptable</span>')}</td>
                 <td>
                     <select onchange="setPromoType(${p.id}, this.value, '${escapeHtml(p.name)}')"
-                        ${p.is_immutable ? 'disabled title="Release the immutable flag first"' : ''}>
+                        ${p.is_immutable ? 'disabled title="Make the playlist preemptable first"' : ''}>
                         ${options(p.promo_type || '')}
                     </select>
                 </td>
             </tr>`).join('')}
     </table>
     <p class="muted" style="margin-top:0.5rem;font-size:0.8rem;">
-        Immutable playlists can't be promo pools — release them on the Playlists page first.
+        Non-preemptable playlists can't be promo pools — make them preemptable on the Playlists page first.
         Multiple playlists may share a type; their clips are unioned into that type's pool.
     </p>`;
 }

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/templates/admin/schedules.html

@@ -47,7 +47,7 @@ async function loadActive() {
     const locked = a.is_immutable && !a.lock_disabled;
     banner.innerHTML = `
         <strong>Active schedule running:</strong> ${escapeHtml(name)}
-        ${a.is_immutable ? '<span class="badge badge-warn">Immutable</span>' : ''}
+        ${a.is_immutable ? '<span class="badge badge-warn">Non-preemptable</span>' : ''}
         ${locked ? '<span class="badge badge-warn">Pay-to-play locked</span>' : '<span class="badge">Unlocked</span>'}
         ${a.estimated_end_at ? `<div class="muted">Ends ~${formatLocalDateTime(a.estimated_end_at)}</div>` : ''}
         <div style="margin-top:0.5rem;">

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/templates/base.html

@@ -4,6 +4,22 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>{% block title %}Queue{% endblock %} — Channel-Z</title>
+    <script>
+        // Set the theme before first paint to avoid a flash of the wrong theme.
+        // Explicit choice in localStorage wins; otherwise follow the OS preference.
+        (function () {
+            try {
+                var saved = localStorage.getItem('wq_theme');
+                var theme = (saved === 'light' || saved === 'dark')
+                    ? saved
+                    : (window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches
+                        ? 'light' : 'dark');
+                document.documentElement.dataset.theme = theme;
+            } catch (e) {
+                document.documentElement.dataset.theme = 'dark';
+            }
+        })();
+    </script>
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Sora:wght@600;700&display=swap">
@@ -27,6 +43,7 @@
             {% else %}
                 <a href="/auth/login">Login</a>
             {% endif %}
+            <button type="button" id="theme-toggle" class="theme-toggle" aria-label="Toggle light/dark theme" title="Toggle light/dark theme"></button>
         </div>
     </nav>
 

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/kryten_webqueue/templates/catalog/browse.html

@@ -101,13 +101,41 @@
     {% endfor %}
 </div>
 
+{% set sort_q = ('&sort=' ~ sort) if (sort and sort != 'default') else '' %}
 {% if not items %}
 <div class="empty-state">
-    <p>No items found.</p>
+    {% if query and (active_category or active_tag) %}
+        <p>No results for "{{ query }}" within the selected filter{% if active_category and active_tag %}s{% endif %}.</p>
+        <p class="muted">
+            Active:
+            {% if active_category %}<strong>category</strong>{% endif %}
+            {% if active_category and active_tag %} and {% endif %}
+            {% if active_tag %}<strong>tag “{{ active_tag }}”</strong>{% endif %}.
+            Try widening your search.
+        </p>
+        <p>
+            <a class="btn btn-sm" href="/catalog/search?q={{ query | urlencode }}{{ sort_q }}">Search without filters</a>
+            <a class="btn btn-sm" href="/catalog/browse">Clear search</a>
+        </p>
+    {% elif query %}
+        <p>No results for "{{ query }}".</p>
+        <p class="muted">Check the spelling or try fewer / different words.</p>
+        <p><a class="btn btn-sm" href="/catalog/browse">Back to browse</a></p>
+    {% elif active_category or active_tag %}
+        <p>No items match the selected filter{% if active_category and active_tag %}s{% endif %}.</p>
+        <p class="muted">
+            Active:
+            {% if active_category %}<strong>category</strong>{% endif %}
+            {% if active_category and active_tag %} and {% endif %}
+            {% if active_tag %}<strong>tag “{{ active_tag }}”</strong>{% endif %}.
+        </p>
+        <p><a class="btn btn-sm" href="/catalog/browse">Clear filters</a></p>
+    {% else %}
+        <p>No items found.</p>
+    {% endif %}
 </div>
 {% endif %}
 
-{% set sort_q = ('&sort=' ~ sort) if (sort and sort != 'default') else '' %}
 <div class="pagination">
     {% if page > 1 %}
         <a href="?page={{ page - 1 }}{% if query %}&q={{ query }}{% endif %}{% if active_category %}&category={{ active_category }}{% endif %}{% if active_tag %}&tag={{ active_tag | urlencode }}{% endif %}{{ sort_q }}" class="btn btn-sm">&larr; Prev</a>
@@ -141,13 +169,13 @@ function applyFacets() {
     const sort = document.getElementById('sort-select').value;
     try { localStorage.setItem('browse_sort', sort); } catch (e) { /* ignore */ }
     const params = new URLSearchParams();
-    // On a search results page, preserve the query and stay on /catalog/search.
+    // On a search results page keep the query AND apply the facets so search
+    // results are narrowed by category/tag (they AND together server-side).
     if (CURRENT_QUERY) {
         params.set('q', CURRENT_QUERY);
-    } else {
-        if (cat) params.set('category', cat);
-        if (tag) params.set('tag', tag);
     }
+    if (cat) params.set('category', cat);
+    if (tag) params.set('tag', tag);
     if (sort && sort !== 'default') params.set('sort', sort);
     const base = CURRENT_QUERY ? '/catalog/search' : '/catalog/browse';
     const qs = params.toString();

{kryten_webqueue-0.15.2 → kryten_webqueue-0.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kryten-webqueue"
-version = "0.15.2"
+version = "0.17.0"
 description = "Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube"
 readme = "README.md"
 license = "MIT"

kryten_webqueue-0.17.0/tests/test_search_facets.py

@@ -0,0 +1,81 @@
+"""Search combines with category/tag facets (Item 4 of the UX polish plan).
+
+A free-text search now ANDs with the selected category and/or tag, mirroring how
+browse() already filters. These tests pin that behavior at the DB layer.
+"""
+
+import pytest
+
+from kryten_webqueue.catalog.db import Database
+
+MEDIACMS = "https://www.dropsugar.com"
+
+
+@pytest.fixture
+async def db(tmp_path):
+    database = Database(str(tmp_path / "search_facets.db"))
+    await database.connect()
+    await database.run_migrations()
+    yield database
+    await database.close()
+
+
+async def _add_catalog(db, token, title):
+    await db.insert_catalog({
+        "friendly_token": token,
+        "title": title,
+        "description": "",
+        "duration_sec": 600,
+        "manifest_url": f"{MEDIACMS}/api/v1/media/cytube/{token}.json?format=json",
+        "thumbnail_url": "",
+        "synced_at": "2026-01-01T00:00:00+00:00",
+    })
+
+
+async def test_search_ands_with_category_and_tag(db):
+    # Three items all matching the query "Dragon", differentiated by facets.
+    await _add_catalog(db, "tok_action", "Dragon Action")
+    await _add_catalog(db, "tok_comedy", "Dragon Comedy")
+    await _add_catalog(db, "tok_plain", "Dragon Plain")
+
+    action_id = await db.upsert_category("Action")
+    comedy_id = await db.upsert_category("Comedy")
+    await db.set_catalog_categories("tok_action", [action_id])
+    await db.set_catalog_categories("tok_comedy", [comedy_id])
+
+    epic_tag = await db.upsert_tag("Epic")
+    await db.set_catalog_tags("tok_action", [epic_tag])
+
+    # Resolve the Action slug (upsert derives it).
+    action_slug = next(c["slug"] for c in await db.get_categories() if c["name"] == "Action")
+
+    # Plain query: all three match.
+    assert {r["friendly_token"] for r in await db.search("Dragon")} == {
+        "tok_action", "tok_comedy", "tok_plain",
+    }
+    assert await db.search_count("Dragon") == 3
+
+    # Query + category: only the Action item.
+    cat_results = {r["friendly_token"] for r in await db.search("Dragon", category=action_slug)}
+    assert cat_results == {"tok_action"}
+    assert await db.search_count("Dragon", category=action_slug) == 1
+
+    # Query + tag: only the Epic-tagged item.
+    tag_results = {r["friendly_token"] for r in await db.search("Dragon", tag="Epic")}
+    assert tag_results == {"tok_action"}
+    assert await db.search_count("Dragon", tag="Epic") == 1
+
+    # Query + category + tag that don't co-occur: empty (true intersection).
+    assert await db.search("Dragon", category=action_slug, tag="Nonexistent") == []
+    assert await db.search_count("Dragon", category=action_slug, tag="Nonexistent") == 0
+
+
+async def test_search_facet_with_no_text_match_is_empty(db):
+    await _add_catalog(db, "tok1", "Comedy Night")
+    comedy_id = await db.upsert_category("Comedy")
+    await db.set_catalog_categories("tok1", [comedy_id])
+    comedy_slug = next(c["slug"] for c in await db.get_categories() if c["name"] == "Comedy")
+
+    # The category matches the item, but the query does not -> no results.
+    assert await db.search("Horror", category=comedy_slug) == []
+    assert await db.search_count("Horror", category=comedy_slug) == 0