kryten-webqueue 0.15.1__tar.gz → 0.16.0__tar.gz

{kryten_webqueue-0.15.1 → kryten_webqueue-0.16.0}/CHANGELOG.md

@@ -6,6 +6,26 @@ 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.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
+
+- **Promos were inserted into immutable playlists during a schedule fire.** A scheduled event clears the queue and loads its items over several seconds (throttled adds + 422 retries), but the event lock that suppresses promos was only recorded *after* the entire load finished. Meanwhile the state poller (every ~3s) saw a partially-built queue with no lock and slotted a general promo between the freshly-added immutable items. `PromoDirector` now exposes a re-entrant `suppressed()` guard that `fire_schedule` (and manual playlist import) holds for the whole load — spanning through `set_active_schedule`, so for an immutable event the persistent lock is already live by the time suppression lifts (a clean handoff with no race window). When suppression releases, the next poll re-baselines now-playing instead of treating the bulk load as content advancing, so no promo fires on the wrong boundary. This also satisfies the general rule: never evaluate promos while a bulk queue insert/append is in progress, regardless of playlist type.
+
+[0.15.2]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.15.2
+
 ## [0.15.1] — 2026-06-17
 
 ### Fixed

{kryten_webqueue-0.15.1 → kryten_webqueue-0.16.0}/PKG-INFO

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

kryten_webqueue-0.16.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.1 → kryten_webqueue-0.16.0}/kryten_webqueue/app.py

@@ -147,6 +147,7 @@ async def lifespan(app: FastAPI):
         db=db, api_gate=api_gate, shadow=shadow, ws_manager=ws_manager,
         add_delay_sec=config.playlist_bulk_add_delay_sec,
         add_max_retries=config.playlist_bulk_add_max_retries,
+        promo_director=promo_director,
     )
     await scheduler.start()
     app.state.scheduler = scheduler

kryten_webqueue-0.16.0/kryten_webqueue/playlists/fire.py

@@ -0,0 +1,136 @@
+import asyncio
+import logging
+from contextlib import nullcontext
+from datetime import datetime, timedelta, UTC
+
+from ..queue.ordering import refund_item
+from .bulk_add import add_item_throttled
+
+logger = logging.getLogger(__name__)
+
+_queue_lock = asyncio.Lock()
+
+
+async def fire_schedule(
+    *,
+    schedule_id: int,
+    api_gate,
+    db,
+    shadow,
+    ws_manager,
+    add_delay_sec: float = 0.0,
+    add_max_retries: int = 0,
+    promo_director=None,
+):
+    """Fire a scheduled playlist: clear queue, refund displaced pay items, load playlist.
+
+    Promo insertion is suppressed for the whole load (via ``promo_director``):
+    promos must never be slotted between items while the playlist is still being
+    built. Suppression spans through ``set_active_schedule`` so that, for an
+    immutable event, the persistent event lock is already recorded by the time
+    suppression lifts — a clean handoff with no window for a stray insertion.
+    """
+    async with _queue_lock:
+        schedule = await db.get_schedule(schedule_id)
+        if not schedule:
+            logger.error(f"Schedule {schedule_id} not found")
+            return
+
+        playlist_id = schedule["playlist_id"]
+        playlist = await db.get_saved_playlist(playlist_id)
+        if not playlist:
+            logger.error(f"Playlist {playlist_id} not found for schedule {schedule_id}")
+            return
+
+        suppress_ctx = (
+            promo_director.suppressed(f"schedule fire {schedule_id}")
+            if promo_director is not None
+            else nullcontext()
+        )
+        with suppress_ctx:
+            # Refund all pay items currently in queue
+            pay_items = await db.get_pay_items()
+            for item in pay_items:
+                await refund_item(api_gate=api_gate, db=db, uid=item["uid"], reason="schedule_displaced")
+
+            # Clear the CyTube playlist
+            await api_gate.playlist_clear()
+
+            # Load scheduled playlist items
+            items = await db.get_saved_playlist_items(playlist_id)
+            total_duration = 0
+            last_item_uid = None
+            for index, item in enumerate(items):
+                # Throttle consecutive adds so CyTube can validate each item before
+                # the next arrives (avoids transient queueFail/422 under load).
+                if index and add_delay_sec:
+                    await asyncio.sleep(add_delay_sec)
+                try:
+                    add_result = await add_item_throttled(
+                        api_gate,
+                        media_type=item["media_type"],
+                        media_id=item["media_id"],
+                        position="end",
+                        max_retries=add_max_retries,
+                        retry_delay_sec=add_delay_sec or 0.5,
+                    )
+                    if isinstance(add_result, dict) and add_result.get("uid") is not None:
+                        last_item_uid = add_result["uid"]
+                    total_duration += item.get("duration_sec", 0) or 0
+                except Exception as e:
+                    logger.warning(f"Schedule fire: failed to add {item['media_id']}: {e}")
+
+            # Append the optional fallback (mutable) playlist AFTER the event items so
+            # the live queue isn't left empty once the event is exhausted. The
+            # fallback items are not part of the "scheduled event", so they do not
+            # change last_item_uid (the event lock still lifts when the last EVENT
+            # item begins) and they remain available for pay-to-play/search.
+            fallback_id = schedule.get("fallback_playlist_id")
+            if fallback_id:
+                fallback_items = await db.get_saved_playlist_items(fallback_id)
+                for index, item in enumerate(fallback_items):
+                    if index and add_delay_sec:
+                        await asyncio.sleep(add_delay_sec)
+                    try:
+                        await add_item_throttled(
+                            api_gate,
+                            media_type=item["media_type"],
+                            media_id=item["media_id"],
+                            position="end",
+                            max_retries=add_max_retries,
+                            retry_delay_sec=add_delay_sec or 0.5,
+                        )
+                    except Exception as e:
+                        logger.warning(f"Schedule fire: failed to add fallback {item['media_id']}: {e}")
+                if fallback_items:
+                    logger.info(
+                        f"Schedule {schedule_id}: appended {len(fallback_items)} fallback item(s) "
+                        f"from playlist {fallback_id}"
+                    )
+
+            # Update active schedule (recorded *inside* the suppression window so
+            # the event lock is live before promos resume).
+            now = datetime.now(UTC)
+            await db.set_active_schedule(
+                schedule_id=schedule_id,
+                playlist_id=playlist_id,
+                is_immutable=playlist.get("is_immutable", False),
+                started_at=now.isoformat(),
+                estimated_end_at=(now + timedelta(seconds=total_duration)).isoformat(),
+                last_item_uid=last_item_uid,
+            )
+
+            # Mark schedule as fired
+            await db.mark_schedule_fired(schedule_id, now.isoformat())
+
+        # Notify WS clients
+        await ws_manager.broadcast({
+            "type": "schedule_fired",
+            "data": {
+                "schedule_id": schedule_id,
+                "playlist_name": playlist["name"],
+                "is_immutable": playlist.get("is_immutable", False),
+            },
+        })
+
+        logger.info(f"Schedule {schedule_id} fired: playlist '{playlist['name']}' ({len(items)} items)")

{kryten_webqueue-0.15.1 → kryten_webqueue-0.16.0}/kryten_webqueue/playlists/importer.py

@@ -1,6 +1,7 @@
 import asyncio
 import logging
 import re
+from contextlib import nullcontext
 
 from .bulk_add import add_item_throttled
 
@@ -62,12 +63,14 @@ def _manifest_url_for_token(token: str, mediacms_url: str | None) -> str | None:
 class PlaylistImporter:
     """Imports items from a saved playlist into the live CyTube queue."""
 
-    def __init__(self, *, api_gate, db, shadow, add_delay_sec: float = 0.0, add_max_retries: int = 0):
+    def __init__(self, *, api_gate, db, shadow, add_delay_sec: float = 0.0, add_max_retries: int = 0,
+                 promo_director=None):
         self._api_gate = api_gate
         self._db = db
         self._shadow = shadow
         self._add_delay_sec = add_delay_sec
         self._add_max_retries = add_max_retries
+        self._promo_director = promo_director
 
     async def import_playlist(self, playlist_id: int) -> dict:
         """Import all items from a saved playlist into the live queue."""
@@ -75,29 +78,38 @@ class PlaylistImporter:
         if not items:
             return {"success": False, "error": "Playlist is empty"}
 
+        # Suppress promo insertion for the whole load so promos aren't slotted
+        # between items while the playlist is still being built.
+        suppress_ctx = (
+            self._promo_director.suppressed(f"playlist import {playlist_id}")
+            if self._promo_director is not None
+            else nullcontext()
+        )
+
         added = 0
         errors = 0
-        for index, item in enumerate(items):
-            # Throttle consecutive adds so CyTube can validate each item before
-            # the next arrives (avoids transient queueFail/422 under load).
-            if index and self._add_delay_sec:
-                await asyncio.sleep(self._add_delay_sec)
-            try:
-                result = await add_item_throttled(
-                    self._api_gate,
-                    media_type=item["media_type"],
-                    media_id=item["media_id"],
-                    position="end",
-                    max_retries=self._add_max_retries,
-                    retry_delay_sec=self._add_delay_sec or 0.5,
-                )
-                if result.get("success"):
-                    added += 1
-                else:
+        with suppress_ctx:
+            for index, item in enumerate(items):
+                # Throttle consecutive adds so CyTube can validate each item before
+                # the next arrives (avoids transient queueFail/422 under load).
+                if index and self._add_delay_sec:
+                    await asyncio.sleep(self._add_delay_sec)
+                try:
+                    result = await add_item_throttled(
+                        self._api_gate,
+                        media_type=item["media_type"],
+                        media_id=item["media_id"],
+                        position="end",
+                        max_retries=self._add_max_retries,
+                        retry_delay_sec=self._add_delay_sec or 0.5,
+                    )
+                    if result.get("success"):
+                        added += 1
+                    else:
+                        errors += 1
+                except Exception as e:
+                    logger.warning(f"Failed to add {item['media_id']}: {e}")
                     errors += 1
-            except Exception as e:
-                logger.warning(f"Failed to add {item['media_id']}: {e}")
-                errors += 1
 
         return {"success": True, "added": added, "errors": errors}
 

{kryten_webqueue-0.15.1 → kryten_webqueue-0.16.0}/kryten_webqueue/playlists/scheduler.py

@@ -27,13 +27,15 @@ def _next_occurrence(rrule_str: str, dtstart: datetime, after: datetime) -> date
 class PlaylistScheduler:
     """APScheduler-based scheduler for playlist fire events."""
 
-    def __init__(self, *, db, api_gate, shadow, ws_manager, add_delay_sec: float = 0.0, add_max_retries: int = 0):
+    def __init__(self, *, db, api_gate, shadow, ws_manager, add_delay_sec: float = 0.0, add_max_retries: int = 0,
+                 promo_director=None):
         self._db = db
         self._api_gate = api_gate
         self._shadow = shadow
         self._ws_manager = ws_manager
         self._add_delay_sec = add_delay_sec
         self._add_max_retries = add_max_retries
+        self._promo_director = promo_director
         self._scheduler = AsyncIOScheduler()
 
     async def start(self):
@@ -100,6 +102,7 @@ class PlaylistScheduler:
             ws_manager=self._ws_manager,
             add_delay_sec=self._add_delay_sec,
             add_max_retries=self._add_max_retries,
+            promo_director=self._promo_director,
         )
         # After an automatic timed fire, advance recurring schedules to their
         # next occurrence and re-arm. (Manual "Fire Now" does NOT advance the

{kryten_webqueue-0.15.1 → kryten_webqueue-0.16.0}/kryten_webqueue/promos/director.py

@@ -22,6 +22,7 @@ director is a no-op while an immutable scheduled event is locking the queue.
 
 import logging
 import random
+from contextlib import contextmanager
 from datetime import datetime, UTC
 
 from ..queue.ordering import _now_playing_uid
@@ -83,6 +84,17 @@ class PromoDirector:
         self._last_clip_token: dict[str, str] = {}   # promo_type -> last clip media_id
         self._seq_index: dict[str, int] = {}          # promo_type -> next sequential index
 
+        # Suppression guard. Held (re-entrantly) by bulk live-queue loaders
+        # (schedule fire, playlist import) so promos are never inserted *into* a
+        # playlist while it is still being built. Without this, the poller runs
+        # every few seconds during the multi-second load and slots promos
+        # between freshly-added items — including immutable ones, because the
+        # event lock isn't recorded until the load finishes.
+        self._suppress_depth: int = 0
+        # Set when suppression lifts so the next poll re-baselines now-playing
+        # instead of treating the post-load discontinuity as content advancing.
+        self._needs_rebaseline: bool = False
+
         # Injectable for tests
         self._rng = random.Random()
         self._now = lambda: datetime.now(UTC)
@@ -97,6 +109,36 @@ class PromoDirector:
         self._config = config
         logger.info("PromoDirector config updated (enabled=%s)", getattr(config, "enabled", None))
 
+    @property
+    def is_suppressed(self) -> bool:
+        """True while a bulk live-queue operation has paused promo insertion."""
+        return self._suppress_depth > 0
+
+    @contextmanager
+    def suppressed(self, reason: str):
+        """Pause promo insertion for the duration of a bulk queue operation.
+
+        Re-entrant: nested holders each bump a depth counter; promos resume only
+        once the outermost holder exits. Use around any operation that adds a
+        run of items to the *live* queue (schedule fire, playlist import) so the
+        director never inserts a promo into a playlist that is still loading.
+
+        On release the next poll re-baselines now-playing rather than counting
+        the load as content advancing, so a promo doesn't fire on the wrong
+        boundary immediately afterwards.
+        """
+        self._suppress_depth += 1
+        if self._suppress_depth == 1:
+            logger.info("Promo insertion suppressed: %s", reason)
+        try:
+            yield
+        finally:
+            self._suppress_depth -= 1
+            if self._suppress_depth <= 0:
+                self._suppress_depth = 0
+                self._needs_rebaseline = True
+                logger.info("Promo insertion resumed (after: %s)", reason)
+
     # --- Play-order helpers -------------------------------------------------
 
     @staticmethod
@@ -365,6 +407,13 @@ class PromoDirector:
         """
         if not self._config.enabled:
             return None
+        if self._suppress_depth > 0:
+            logger.debug(
+                "Viewer's-Choice skipped for paid uid=%s: insertion suppressed "
+                "(bulk queue operation in progress)",
+                content_uid,
+            )
+            return None
         items = self._shadow.items
         if self._has_lead_in(content_uid, items):
             logger.debug(
@@ -392,9 +441,31 @@ class PromoDirector:
         if not cfg.enabled:
             return
 
+        # Frozen while a bulk live-queue operation (schedule fire / playlist
+        # import) is loading items. Promos must never land *inside* a playlist
+        # that is still being built — this is what slips promos between immutable
+        # items before the event lock is recorded.
+        if self._suppress_depth > 0:
+            logger.debug(
+                "Promo on_poll skipped: insertion suppressed (bulk queue operation in progress)"
+            )
+            return
+
         np_uid = await _now_playing_uid(self._api_gate, self._shadow)
         np_is_promo = self._is_promo_uid(np_uid)
 
+        # After a bulk queue operation the playlist is discontinuous; re-baseline
+        # now-playing without counting it as content advancing so we don't fire a
+        # promo on the wrong boundary on the very next cycle.
+        if self._needs_rebaseline:
+            self._needs_rebaseline = False
+            self._last_np_uid = np_uid
+            self._last_np_is_promo = np_is_promo
+            logger.debug(
+                "Promo baseline reset after bulk queue operation (np_uid=%s)", np_uid
+            )
+            return
+
         # Advance detection: a finished *content* item bumps the cadence counter.
         if np_uid != self._last_np_uid:
             if self._last_np_uid is not None and not self._last_np_is_promo:

{kryten_webqueue-0.15.1 → kryten_webqueue-0.16.0}/kryten_webqueue/routes/admin_playlists.py

@@ -112,6 +112,7 @@ async def import_to_live(request: Request, playlist_id: int, user: dict = Depend
         shadow=request.app.state.shadow,
         add_delay_sec=config.playlist_bulk_add_delay_sec,
         add_max_retries=config.playlist_bulk_add_max_retries,
+        promo_director=getattr(request.app.state, "promo_director", None),
     )
     result = await importer.import_playlist(playlist_id)
     return result

{kryten_webqueue-0.15.1 → kryten_webqueue-0.16.0}/kryten_webqueue/routes/admin_schedules.py

@@ -121,6 +121,7 @@ async def fire_now(request: Request, schedule_id: int, user: dict = Depends(requ
         ws_manager=request.app.state.ws_manager,
         add_delay_sec=config.playlist_bulk_add_delay_sec,
         add_max_retries=config.playlist_bulk_add_max_retries,
+        promo_director=getattr(request.app.state, "promo_director", None),
     )
     return {"success": True}