kryten-webqueue 0.24.0__tar.gz → 0.26.0__tar.gz

{kryten_webqueue-0.24.0 → kryten_webqueue-0.26.0}/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.26.0] — 2026-06-22
+
+### Changed
+
+- **Race view is now smooth, with cars, drivers, and live commentary.** The economy now ships the whole race as a precomputed timeline (economy 0.13.0), so the `/race` view animates it client-side with `requestAnimationFrame` + interpolation — cars glide continuously and re-sync to the server clock instead of jumping between polls. Visual overhaul: each racer is a little CSS race **car** (cabin + wheels) that drives down a striped track from a colour start-cap to a checkered finish, with the **driver's name** (e.g. *Manuel Transmission*) under its colour, a live **position** column, and bet totals. A **commentary banner** above the field shows play-by-play (start, driver-named lead changes, close-finish, winner call) with the newest line replacing the last. Now shows all **6** cars.
+- **Race WebSocket bandwidth cut.** The heavy position timeline is broadcast only once per race; subsequent frames carry just the server `elapsed` re-sync hint (the browser self-animates), so per-tick traffic stays tiny even with many spectators. Late-joiners still receive the full timeline on connect.
+
+[0.26.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.26.0
+
+## [0.25.0] — 2026-06-22
+
+### Added
+
+- **Live web race view at `/race`.** The economy's racing game play-by-play moved off public chat (which flooded the channel) and onto a visual web view anyone can watch — no login required. A new public page animates the race in real time: each racer glides along its lane toward the finish, with live positions, odds, the betting countdown, per-colour bet totals, and a winner banner + payouts when it ends. A background `RacePoller` polls api-gate's `GET /economy/race` adaptively (fast while a race is live, backing off when idle) and pushes frames to spectators over a dedicated public `/ws/race` WebSocket; a newly-opened view is immediately shown a race already in progress. The race WebSocket carries only race frames (no user or queue data), and a “Race” link was added to the nav.
+
+[0.25.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.25.0
+
 ## [0.24.0] — 2026-06-21
 
 ### Added

{kryten_webqueue-0.24.0 → kryten_webqueue-0.26.0}/PKG-INFO

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

{kryten_webqueue-0.24.0 → kryten_webqueue-0.26.0}/kryten_webqueue/api_gate/client.py

@@ -47,6 +47,16 @@ class ApiGateClient:
     async def get_user(self, username: str) -> dict:
         return await self.get(f"/state/user/{username}")
 
+    # --- Economy: race view ---
+
+    async def get_race_state(self) -> dict:
+        """Live race snapshot for the web race view.
+
+        Returns ``{"active": bool, "frame": {...}|None}`` from api-gate's
+        ``GET /economy/race`` (which proxies the economy ``race.state`` command).
+        """
+        return await self.get("/economy/race")
+
     # --- Playlist CRUD ---
 
     async def playlist_add(self, media_type: str, media_id: str, *, position: str = "end", temp: bool = True) -> dict:

{kryten_webqueue-0.24.0 → kryten_webqueue-0.26.0}/kryten_webqueue/app.py

@@ -16,6 +16,7 @@ from .jobs import JobManager
 from .catalog.images import CoverArtResolver
 from .queue.shadow import QueueShadow
 from .queue.poller import StatePoller
+from .queue.race_poller import RacePoller
 from .queue.presence import PresenceRefundMonitor
 from .promos.director import PromoDirector
 from .ws.manager import WebSocketManager
@@ -114,6 +115,13 @@ async def lifespan(app: FastAPI):
     ws_manager = WebSocketManager()
     app.state.ws_manager = ws_manager
 
+    # Public race-view WebSocket manager (anonymous spectators) + poller.
+    race_ws_manager = WebSocketManager()
+    app.state.race_ws_manager = race_ws_manager
+    race_poller = RacePoller(api_gate=api_gate, ws_manager=race_ws_manager)
+    await race_poller.start()
+    app.state.race_poller = race_poller
+
     # Queue shadow
     shadow = QueueShadow(db)
     await shadow.load_from_db()
@@ -218,6 +226,7 @@ async def lifespan(app: FastAPI):
     for task in bg_tasks:
         task.cancel()
     await poller.stop()
+    await race_poller.stop()
     await scheduler.stop()
     await presence_monitor.stop()
     await catalog_sync.close()

kryten_webqueue-0.26.0/kryten_webqueue/queue/race_poller.py

@@ -0,0 +1,120 @@
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class RacePoller:
+    """Polls api-gate's race view and pushes frames to race spectators.
+
+    Adaptive cadence: while a race is live it polls quickly (``active_interval``)
+    so the web view animates smoothly; when idle it backs off
+    (``idle_interval``). The latest frame is cached so a newly-connected
+    spectator can be shown the race already in progress.
+
+    Broadcast messages (to the public race WebSocket manager):
+    - ``{"type": "race_frame", "data": <frame>}`` each poll while a race is live.
+    - ``{"type": "race_clear"}`` once, when a race ends and the view goes idle.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_gate,
+        ws_manager,
+        active_interval: float = 1.5,
+        idle_interval: float = 4.0,
+    ):
+        self._api_gate = api_gate
+        self._ws_manager = ws_manager
+        self._active_interval = active_interval
+        self._idle_interval = idle_interval
+        self._task: asyncio.Task | None = None
+        self._last_frame: dict | None = None
+        # race_id whose heavy timeline has already been broadcast; subsequent
+        # frames for the same race are sent "light" (timeline body stripped).
+        self._bcast_race_id: str | None = None
+
+    @property
+    def last_frame(self) -> dict | None:
+        """The most recent live frame, or None when no race is active."""
+        return self._last_frame
+
+    async def start(self):
+        self._task = asyncio.create_task(self._loop())
+        logger.info(
+            "RacePoller started (active=%.1fs idle=%.1fs)",
+            self._active_interval, self._idle_interval,
+        )
+
+    async def stop(self):
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            logger.info("RacePoller stopped")
+
+    async def _poll_once(self) -> float:
+        """Run one poll; broadcast as needed. Returns the next sleep interval."""
+        try:
+            result = await self._api_gate.get_race_state()
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.debug("Race poll error: %s", e)
+            # Treat an error like "idle" but don't spuriously clear an active
+            # view — just back off and retry.
+            return self._idle_interval
+
+        active = bool(result.get("active")) and result.get("frame") is not None
+        if active:
+            frame = result["frame"]
+            self._last_frame = frame
+            await self._ws_manager.broadcast(
+                {"type": "race_frame", "data": self._strip_repeat_timeline(frame)}
+            )
+            return self._active_interval
+
+        # Not active. If we were showing a race, tell spectators to clear once.
+        if self._last_frame is not None:
+            self._last_frame = None
+            self._bcast_race_id = None
+            await self._ws_manager.broadcast({"type": "race_clear"})
+        return self._idle_interval
+
+    def _strip_repeat_timeline(self, frame: dict) -> dict:
+        """Drop the heavy timeline body after its first broadcast per race.
+
+        The browser caches the timeline and self-animates, so resending ~100
+        position frames every poll is pure waste (especially with many
+        spectators). The first racing frame for a race carries the full
+        timeline; later frames keep only ``elapsed`` (a tiny re-sync hint).
+        Betting/finished frames and new-race frames always pass through whole.
+        """
+        rid = frame.get("race_id")
+        tl = frame.get("timeline")
+        if tl is None:
+            # No timeline (betting/finished) — pass through, reset on new race.
+            if frame.get("phase") != "racing":
+                self._bcast_race_id = None if frame.get("phase") == "finished" else self._bcast_race_id
+            return frame
+        if rid == self._bcast_race_id:
+            light = dict(frame)
+            light["timeline"] = {"elapsed": tl.get("elapsed", 0)}
+            return light
+        # First racing frame for this race — send full timeline, then mark sent.
+        self._bcast_race_id = rid
+        return frame
+
+    async def _loop(self):
+        while True:
+            try:
+                delay = await self._poll_once()
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                logger.warning("RacePoller loop error: %s", e)
+                delay = self._idle_interval
+            await asyncio.sleep(delay)

{kryten_webqueue-0.24.0 → kryten_webqueue-0.26.0}/kryten_webqueue/routes/pages.py

@@ -71,6 +71,13 @@ async def login_page(request: Request):
     return templates.TemplateResponse(request, "auth/login.html", {"user": None})
 
 
+@router.get("/race", response_class=HTMLResponse)
+async def race_view(request: Request):
+    """Public race spectator view — no auth. Streams frames over /ws/race."""
+    user = _get_user_or_none(request)
+    return templates.TemplateResponse(request, "race.html", {"user": user})
+
+
 @router.get("/catalog/browse", response_class=HTMLResponse)
 async def catalog_browse_page(request: Request, category: str | None = None,
                               tag: str | None = None, page: int = 1,

{kryten_webqueue-0.24.0 → kryten_webqueue-0.26.0}/kryten_webqueue/templates/base.html

@@ -34,6 +34,7 @@
         <div class="nav-links">
             <a href="/catalog/browse">Browse</a>
             <a href="/queue">Queue</a>
+            <a href="/race">Race</a>
             {% if user %}
                 <a href="/user/dashboard">{{ user.username }}</a>
                 {% if user.rank >= 3 %}

kryten_webqueue-0.26.0/kryten_webqueue/templates/race.html

@@ -0,0 +1,395 @@
+{% extends "base.html" %}
+{% block title %}Live Race{% endblock %}
+{% block body_class %}race-page{% endblock %}
+
+{% block head %}
+<style>
+  .race-wrap { max-width: 960px; margin: 0 auto; }
+  .race-head { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; flex-wrap: wrap; }
+  .race-head h1 { font-family: 'Sora', sans-serif; margin: 0; }
+  .race-status { font-weight: 600; opacity: 0.9; }
+  .race-status .pill { padding: 0.18rem 0.7rem; border-radius: 999px; font-size: 0.82rem; }
+  .pill-betting { background: #1f6feb33; color: #79c0ff; }
+  .pill-racing  { background: #2ea04333; color: #7ee787; }
+  .pill-finished{ background: #d2992233; color: #f0c674; }
+  .pill-idle    { background: #6e768166; color: #c9d1d9; }
+
+  /* Commentary feed — newest line, fades on change. */
+  .race-commentary {
+    margin: 0.9rem 0 0.4rem; min-height: 1.9rem; display: flex; align-items: center;
+    gap: 0.5rem; padding: 0.5rem 0.85rem; border-radius: 10px;
+    background: linear-gradient(90deg, #161b22, #0d1117);
+    border: 1px solid #232a33; font-size: 1.02rem; font-weight: 500;
+  }
+  .race-commentary .mic { opacity: 0.7; }
+  .race-commentary .txt { transition: opacity 0.25s ease; }
+  .race-commentary .txt.swap { opacity: 0; }
+
+  .race-track { margin: 0.6rem 0 1rem; display: flex; flex-direction: column; gap: 0.5rem; }
+  .lane {
+    position: relative; display: grid; grid-template-columns: 2.2rem 12.5rem 1fr auto;
+    align-items: center; gap: 0.7rem; padding: 0.4rem 0.55rem; border-radius: 11px;
+    background: #11141a; border: 1px solid #232a33; transition: border-color 0.3s, box-shadow 0.3s;
+  }
+  .lane.win { border-color: #f0c674; box-shadow: 0 0 0 1px #f0c67455, 0 0 22px #f0c67433; }
+  .lane-pos {
+    font-weight: 800; text-align: center; font-variant-numeric: tabular-nums;
+    color: #c9d1d9; font-size: 0.95rem;
+  }
+  .lane-pos.p1 { color: #f0c674; }
+  .lane-label { display: flex; flex-direction: column; line-height: 1.15; min-width: 0; }
+  .lane-color { display: flex; align-items: center; gap: 0.4rem; font-weight: 700; font-size: 0.92rem; }
+  .lane-swatch { width: 0.8rem; height: 0.8rem; border-radius: 50%; flex: 0 0 auto; box-shadow: 0 0 0 1px #0006 inset; }
+  .lane-driver { font-size: 0.78rem; opacity: 0.72; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .lane-meta { text-align: right; font-variant-numeric: tabular-nums; }
+  .lane-odds { font-weight: 700; font-size: 0.9rem; }
+  .lane-amt { font-size: 0.74rem; opacity: 0.72; }
+
+  /* Track rail with start/finish color markers and a moving car. */
+  .lane-rail {
+    position: relative; height: 30px; border-radius: 8px;
+    background: repeating-linear-gradient(90deg, #0c0e12 0 18px, #0e1117 18px 36px);
+    border: 1px solid #1c222b; overflow: hidden;
+  }
+  .rail-cap { position: absolute; top: 0; bottom: 0; width: 5px; opacity: 0.85; }
+  .rail-cap.start { left: 0; border-radius: 8px 0 0 8px; }
+  .rail-cap.finish {
+    right: 0; border-radius: 0 8px 8px 0;
+    background-image: repeating-linear-gradient(45deg, #fff 0 4px, #000 4px 8px) !important;
+    opacity: 0.55; width: 8px;
+  }
+  .car {
+    position: absolute; top: 50%; left: 0; transform: translate(-50%, -50%);
+    width: 30px; height: 15px; border-radius: 5px 7px 4px 4px;
+    box-shadow: 0 1px 3px #000a, inset 0 -3px 4px #0004; will-change: left;
+  }
+  .car::before {  /* cabin */
+    content: ''; position: absolute; left: 6px; top: -4px; width: 12px; height: 7px;
+    border-radius: 4px 4px 0 0; background: #ffffffcc;
+  }
+  .car::after {   /* wheels */
+    content: ''; position: absolute; left: 3px; right: 3px; bottom: -3px; height: 5px;
+    background:
+      radial-gradient(circle at 5px 50%, #111 0 3px, transparent 3px),
+      radial-gradient(circle at calc(100% - 5px) 50%, #111 0 3px, transparent 3px);
+  }
+
+  .race-side { display: flex; gap: 1.6rem; flex-wrap: wrap; font-variant-numeric: tabular-nums; opacity: 0.92; }
+  .race-side .stat b { font-size: 1.12rem; }
+  .race-winner { margin: 1rem 0; padding: 0.8rem 1.05rem; border-radius: 11px;
+    background: #d2992218; border: 1px solid #f0c67455; }
+  .race-winner h2 { margin: 0 0 0.4rem; font-family: 'Sora', sans-serif; }
+  .race-payouts { margin: 0.3rem 0 0; padding-left: 1.15rem; }
+  .race-payouts li { margin: 0.1rem 0; }
+  .race-idle { text-align: center; opacity: 0.7; padding: 3rem 1rem; }
+
+  @media (max-width: 640px) {
+    .lane { grid-template-columns: 1.7rem 1fr auto; }
+    .lane-rail { grid-column: 1 / -1; order: 5; }
+    .lane-driver { white-space: normal; }
+  }
+</style>
+{% endblock %}
+
+{% block content %}
+<div class="race-wrap">
+  <div class="race-head">
+    <h1>🏁 Live Race</h1>
+    <div class="race-status" id="race-status"><span class="pill pill-idle">Connecting…</span></div>
+  </div>
+
+  <div class="race-commentary" id="race-commentary" hidden>
+    <span class="mic">📣</span><span class="txt" id="commentary-txt"></span>
+  </div>
+
+  <div id="race-body">
+    <div class="race-idle" id="race-idle">Waiting for the next race…</div>
+    <div class="race-track" id="race-track" hidden></div>
+    <div class="race-side" id="race-side" hidden></div>
+    <div class="race-winner" id="race-winner" hidden></div>
+  </div>
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script>
+(function () {
+  const COLORS = {
+    Blue: '#3b82f6', Red: '#ef4444', Green: '#22c55e',
+    Yellow: '#eab308', Purple: '#a855f7', Orange: '#f97316',
+  };
+  const colorOf = (c) => COLORS[c] || '#9aa4af';
+
+  const statusEl = document.getElementById('race-status');
+  const idleEl   = document.getElementById('race-idle');
+  const trackEl  = document.getElementById('race-track');
+  const sideEl   = document.getElementById('race-side');
+  const winnerEl = document.getElementById('race-winner');
+  const commEl   = document.getElementById('race-commentary');
+  const commTxt  = document.getElementById('commentary-txt');
+
+  const lanes = new Map();   // color -> { row, car, pos, amt }
+  let laneSig = '';
+  let raceId = null;
+
+  // playback state
+  let timeline = null;       // {frame_dt, duration, frames, commentary, elapsed}
+  let currentColors = [];
+  let playbackStart = 0;     // performance.now() baseline
+  let rafId = 0;
+  let commentaryShown = -1;
+
+  function esc(s) {
+    return String(s).replace(/[&<>"']/g, c => (
+      { '&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;' }[c]
+    ));
+  }
+  function setStatus(kind, text) {
+    statusEl.innerHTML = '<span class="pill pill-' + kind + '">' + esc(text) + '</span>';
+  }
+  function setCommentary(text) {
+    if (!text) return;
+    commEl.hidden = false;
+    if (commTxt.textContent === text) return;
+    commTxt.classList.add('swap');
+    setTimeout(() => { commTxt.textContent = text; commTxt.classList.remove('swap'); }, 130);
+  }
+
+  function buildLanes(racers) {
+    trackEl.innerHTML = '';
+    lanes.clear();
+    for (const r of racers) {
+      const col = colorOf(r.color);
+      const row = document.createElement('div');
+      row.className = 'lane';
+      row.innerHTML =
+        '<div class="lane-pos"></div>' +
+        '<div class="lane-label">' +
+          '<span class="lane-color"><span class="lane-swatch" style="background:' + col + '"></span>' + esc(r.color) + '</span>' +
+          '<span class="lane-driver">' + esc(r.name || '') + '</span>' +
+        '</div>' +
+        '<div class="lane-rail">' +
+          '<span class="rail-cap start" style="background:' + col + '"></span>' +
+          '<span class="rail-cap finish"></span>' +
+          '<span class="car" style="background:' + col + '"></span>' +
+        '</div>' +
+        '<div class="lane-meta">' +
+          '<div class="lane-odds">' + esc(r.odds || '') + '</div>' +
+          '<div class="lane-amt"></div>' +
+        '</div>';
+      trackEl.appendChild(row);
+      lanes.set(r.color, {
+        row,
+        car: row.querySelector('.car'),
+        pos: row.querySelector('.lane-pos'),
+        amt: row.querySelector('.lane-amt'),
+      });
+    }
+  }
+
+  // Place a car along its rail (pct 0..100 → left 3%..97% so it stays on track).
+  function placeCar(color, pct) {
+    const lane = lanes.get(color);
+    if (!lane) return;
+    const left = 3 + Math.max(0, Math.min(100, pct)) * 0.94;
+    lane.car.style.left = left + '%';
+  }
+
+  function updateRanking(colors, values) {
+    const order = colors
+      .map((c, i) => [c, values[i]])
+      .sort((a, b) => b[1] - a[1]);
+    order.forEach(([c], idx) => {
+      const lane = lanes.get(c);
+      if (!lane) return;
+      lane.pos.textContent = '#' + (idx + 1);
+      lane.pos.classList.toggle('p1', idx === 0);
+    });
+  }
+
+  function applyBets(frame) {
+    const bets = frame.bets_by_color || {};
+    for (const [color, lane] of lanes) {
+      const b = bets[color];
+      lane.amt.textContent = b ? ('💰 ' + b.amount.toLocaleString()) : '';
+    }
+  }
+
+  function sideStats(frame) {
+    const sym = frame.symbol || '';
+    sideEl.hidden = false;
+    sideEl.innerHTML =
+      '<div class="stat">Pool <b>' + (frame.pool || 0).toLocaleString() + ' ' + esc(sym) + '</b></div>' +
+      '<div class="stat">Bettors <b>' + (frame.bettor_count || 0) + '</b></div>' +
+      (frame.phase === 'betting'
+        ? '<div class="stat">Min bet <b>' + (frame.min_bet || 0).toLocaleString() + ' ' + esc(sym) + '</b></div>'
+        : '');
+  }
+
+  // ── Timeline playback (smooth, rAF + interpolation) ────────
+  function posAt(t) {
+    const { frame_dt, frames } = timeline;
+    const pos = t / frame_dt;
+    let i = Math.floor(pos);
+    if (i >= frames.length - 1) return frames[frames.length - 1].slice();
+    const frac = pos - i;
+    const a = frames[i], b = frames[i + 1];
+    return a.map((v, j) => v + (b[j] - v) * frac);
+  }
+
+  function showCommentaryUpTo(t) {
+    if (!timeline.commentary) return;
+    let idx = commentaryShown;
+    for (let k = commentaryShown + 1; k < timeline.commentary.length; k++) {
+      if (timeline.commentary[k].t <= t) idx = k; else break;
+    }
+    if (idx !== commentaryShown) {
+      commentaryShown = idx;
+      setCommentary(timeline.commentary[idx].text);
+    }
+  }
+
+  function frameTick(now) {
+    if (!timeline) return;
+    let t = (now - playbackStart) / 1000;
+    if (t < 0) t = 0;
+    const done = t >= timeline.duration;
+    if (done) t = timeline.duration;
+
+    const row = posAt(t);
+    currentColors.forEach((c, j) => placeCar(c, row[j]));
+    updateRanking(currentColors, row);
+    showCommentaryUpTo(t);
+
+    if (!done) rafId = requestAnimationFrame(frameTick);
+  }
+
+  function startPlayback(frame) {
+    timeline = frame.timeline;
+    currentColors = frame.racers.map(r => r.color);
+    commentaryShown = -1;
+    const elapsed = Math.max(0, timeline.elapsed || 0);
+    playbackStart = performance.now() - elapsed * 1000;
+    cancelAnimationFrame(rafId);
+    rafId = requestAnimationFrame(frameTick);
+  }
+
+  function resync(frame) {
+    // Gently correct drift (e.g. after a backgrounded tab) without jumping.
+    const elapsed = Math.max(0, frame.timeline.elapsed || 0);
+    const localT = (performance.now() - playbackStart) / 1000;
+    if (Math.abs(localT - elapsed) > 1.2) {
+      playbackStart = performance.now() - elapsed * 1000;
+    }
+    timeline.commentary = frame.timeline.commentary || timeline.commentary;
+  }
+
+  // ── Frame router ───────────────────────────────────────────
+  function render(frame) {
+    idleEl.hidden = true;
+    trackEl.hidden = false;
+
+    const sig = frame.racers.map(r => r.color).join('|');
+    const isNewRace = frame.race_id !== raceId || sig !== laneSig;
+    if (isNewRace) {
+      buildLanes(frame.racers);
+      laneSig = sig;
+      raceId = frame.race_id;
+      timeline = null;
+      cancelAnimationFrame(rafId);
+    }
+    applyBets(frame);
+    sideStats(frame);
+
+    if (frame.phase === 'betting') {
+      cancelAnimationFrame(rafId); timeline = null;
+      frame.racers.forEach(r => placeCar(r.color, 0));
+      updateRanking(frame.racers.map(r => r.color), frame.racers.map(() => 0));
+      winnerEl.hidden = true;
+      setStatus('betting', 'Betting open — ' + (frame.betting_closes_in || 0) + 's left');
+      setCommentary('Place your bets! ' + frame.racers.length + ' cars on the grid.');
+    } else if (frame.phase === 'racing') {
+      winnerEl.hidden = true;
+      setStatus('racing', 'They\u2019re off!');
+      if (frame.timeline) {
+        const hasFrames = Array.isArray(frame.timeline.frames) && frame.timeline.frames.length;
+        if (!timeline && hasFrames) startPlayback(frame);
+        else if (timeline) resync(frame);
+        // else: a light sync arrived before the full timeline — wait for it.
+      }
+    } else if (frame.phase === 'finished') {
+      cancelAnimationFrame(rafId); timeline = null;
+      showFinished(frame);
+    }
+  }
+
+  function showFinished(frame) {
+    setStatus('finished', 'Finished');
+    const winnerColor = frame.winner && frame.winner.color;
+    frame.racers.forEach(r => placeCar(r.color, r.pct || 0));
+    updateRanking(frame.racers.map(r => r.color), frame.racers.map(r => r.pct || 0));
+    for (const [c, lane] of lanes) lane.row.classList.toggle('win', c === winnerColor);
+
+    const sym = frame.symbol || '';
+    if (frame.winner) {
+      const w = frame.winner;
+      const driver = w.name ? (' — ' + esc(w.name)) : '';
+      const payouts = (frame.payouts || []).slice(0, 6)
+        .map(p => '<li>' + esc(p.username) + ' <b>+' + (p.net || 0).toLocaleString() + ' ' + esc(sym) + '</b></li>')
+        .join('');
+      winnerEl.hidden = false;
+      winnerEl.innerHTML =
+        '<h2><span class="lane-swatch" style="display:inline-block;vertical-align:middle;background:' + colorOf(w.color) + '"></span> ' +
+          esc(w.color) + ' wins!' + driver + '</h2>' +
+        (payouts ? '<ul class="race-payouts">' + payouts + '</ul>' : '<div>No winning bets this race.</div>');
+      setCommentary('🏆 ' + esc(w.color) + (w.name ? ' (' + esc(w.name) + ')' : '') + ' takes the checkered flag!');
+    }
+  }
+
+  function showIdle() {
+    laneSig = ''; raceId = null; timeline = null;
+    cancelAnimationFrame(rafId);
+    lanes.clear();
+    trackEl.hidden = true; sideEl.hidden = true; winnerEl.hidden = true;
+    commEl.hidden = true;
+    idleEl.hidden = false;
+    setStatus('idle', 'No race running');
+  }
+
+  // ── WebSocket with auto-reconnect ──────────────────────────
+  let ws = null, retry = 0, pingTimer = null;
+  function connect() {
+    const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+    ws = new WebSocket(proto + '://' + location.host + '/ws/race');
+    ws.onopen = () => {
+      retry = 0; setStatus('idle', 'Connected');
+      clearInterval(pingTimer);
+      pingTimer = setInterval(() => { try { ws.send(JSON.stringify({ type: 'ping' })); } catch (e) {} }, 25000);
+    };
+    ws.onmessage = (ev) => {
+      let m; try { m = JSON.parse(ev.data); } catch (e) { return; }
+      if (m.type === 'race_frame') render(m.data);
+      else if (m.type === 'race_clear') showIdle();
+    };
+    ws.onclose = () => {
+      clearInterval(pingTimer);
+      setStatus('idle', 'Reconnecting…');
+      retry = Math.min(retry + 1, 6);
+      setTimeout(connect, 500 * retry);
+    };
+    ws.onerror = () => { try { ws.close(); } catch (e) {} };
+  }
+
+  // Re-sync playback when returning to a backgrounded tab.
+  document.addEventListener('visibilitychange', () => {
+    if (!document.hidden && timeline) {
+      cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(frameTick);
+    }
+  });
+
+  showIdle();
+  connect();
+})();
+</script>
+{% endblock %}

{kryten_webqueue-0.24.0 → kryten_webqueue-0.26.0}/kryten_webqueue/ws/handler.py

@@ -1,5 +1,6 @@
 import json
 import logging
+import uuid
 from fastapi import APIRouter, WebSocket, WebSocketDisconnect
 import jwt
 
@@ -57,3 +58,47 @@ async def websocket_endpoint(ws: WebSocket):
         logger.warning(f"WS error for {username}: {e}")
     finally:
         await manager.disconnect(username)
+
+
+@router.websocket("/ws/race")
+async def race_websocket_endpoint(ws: WebSocket):
+    """Public race-view WebSocket. No authentication — streams only race frames.
+
+    Anyone watching the channel can open the race view without logging into the
+    queue dashboard. Connections are anonymous (keyed by a random id) and only
+    ever receive race frames (no user/queue data), so this is safe to expose.
+    """
+    await ws.accept()
+    manager = ws.app.state.race_ws_manager
+    poller = getattr(ws.app.state, "race_poller", None)
+    conn_id = uuid.uuid4().hex
+
+    await manager.connect(conn_id, ws)
+
+    # Show a race that's already in progress to a late-joining spectator.
+    try:
+        if poller is not None and poller.last_frame is not None:
+            await ws.send_text(
+                json.dumps({"type": "race_frame", "data": poller.last_frame})
+            )
+    except Exception:
+        await manager.disconnect(conn_id)
+        return
+
+    # Keep the socket open; ignore inbound except ping/pong.
+    try:
+        while True:
+            text = await ws.receive_text()
+            try:
+                msg = json.loads(text)
+            except json.JSONDecodeError:
+                continue
+            if msg.get("type") == "ping":
+                await ws.send_text(json.dumps({"type": "pong"}))
+    except WebSocketDisconnect:
+        pass
+    except Exception as e:
+        logger.debug(f"Race WS error: {e}")
+    finally:
+        await manager.disconnect(conn_id)
+

{kryten_webqueue-0.24.0 → kryten_webqueue-0.26.0}/pyproject.toml

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

kryten_webqueue-0.26.0/tests/test_race_poller.py

@@ -0,0 +1,163 @@
+"""RacePoller — adaptive race-frame polling + WebSocket broadcast.
+
+Drives ``_poll_once()`` directly (the loop is just sleep + retry) to assert the
+broadcast/cache/back-off behaviour without real timers or sockets.
+"""
+
+from kryten_webqueue.queue.race_poller import RacePoller
+
+
+class _FakeApiGate:
+    def __init__(self, results):
+        # results: list of dicts to return, or Exception instances to raise.
+        self._results = list(results)
+        self.calls = 0
+
+    async def get_race_state(self):
+        self.calls += 1
+        val = self._results[min(self.calls - 1, len(self._results) - 1)]
+        if isinstance(val, Exception):
+            raise val
+        return val
+
+
+class _FakeWs:
+    def __init__(self):
+        self.messages = []
+
+    async def broadcast(self, message):
+        self.messages.append(message)
+
+
+async def test_active_frame_broadcasts_and_caches():
+    ws = _FakeWs()
+    frame = {"phase": "racing", "tick": 1}
+    poller = RacePoller(
+        api_gate=_FakeApiGate([{"active": True, "frame": frame}]),
+        ws_manager=ws, active_interval=1.5, idle_interval=4.0,
+    )
+    delay = await poller._poll_once()
+    assert delay == 1.5
+    assert poller.last_frame == frame
+    assert ws.messages == [{"type": "race_frame", "data": frame}]
+
+
+async def test_idle_without_prior_does_not_broadcast():
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([{"active": False, "frame": None}]),
+        ws_manager=ws,
+    )
+    delay = await poller._poll_once()
+    assert delay == poller._idle_interval
+    assert ws.messages == []
+    assert poller.last_frame is None
+
+
+async def test_clear_broadcast_once_after_active():
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([
+            {"active": True, "frame": {"phase": "racing"}},
+            {"active": False, "frame": None},
+            {"active": False, "frame": None},
+        ]),
+        ws_manager=ws,
+    )
+    await poller._poll_once()   # active
+    await poller._poll_once()   # transitions to idle → one clear
+    await poller._poll_once()   # still idle → no repeat
+    assert [m["type"] for m in ws.messages] == ["race_frame", "race_clear"]
+    assert poller.last_frame is None
+
+
+async def test_active_false_with_stale_frame_is_idle():
+    """``active: true`` but a null frame is treated as no race (defensive)."""
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([{"active": True, "frame": None}]),
+        ws_manager=ws,
+    )
+    delay = await poller._poll_once()
+    assert delay == poller._idle_interval
+    assert ws.messages == []
+    assert poller.last_frame is None
+
+
+async def test_error_backs_off_without_clearing():
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([
+            {"active": True, "frame": {"phase": "racing"}},
+            RuntimeError("nats hiccup"),
+        ]),
+        ws_manager=ws,
+    )
+    await poller._poll_once()            # active → caches frame
+    delay = await poller._poll_once()    # error
+    assert delay == poller._idle_interval
+    # No spurious clear; the cached frame is retained so a reconnecting
+    # spectator still sees the race in progress.
+    assert poller.last_frame == {"phase": "racing"}
+    assert [m["type"] for m in ws.messages] == ["race_frame"]
+
+
+def _racing_frame(race_id, elapsed, n_frames=3):
+    return {
+        "active": True,
+        "frame": {
+            "race_id": race_id,
+            "phase": "racing",
+            "timeline": {
+                "frame_dt": 0.3,
+                "duration": 1.0,
+                "elapsed": elapsed,
+                "frames": [[0.0]] * n_frames,
+                "commentary": [{"t": 0.0, "text": "go"}],
+            },
+        },
+    }
+
+
+async def test_full_timeline_sent_once_then_stripped():
+    """First racing frame carries the full timeline; later frames for the same
+    race carry only ``elapsed`` (the browser self-animates)."""
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([
+            _racing_frame("race-A", 0.0),
+            _racing_frame("race-A", 0.3),
+            _racing_frame("race-A", 0.6),
+        ]),
+        ws_manager=ws,
+    )
+    await poller._poll_once()
+    await poller._poll_once()
+    await poller._poll_once()
+
+    first = ws.messages[0]["data"]["timeline"]
+    assert "frames" in first and len(first["frames"]) == 3  # full
+
+    for later in ws.messages[1:]:
+        tl = later["data"]["timeline"]
+        assert tl == {"elapsed": tl["elapsed"]}  # light: elapsed only
+    assert [m["data"]["timeline"]["elapsed"] for m in ws.messages] == [0.0, 0.3, 0.6]
+    # last_frame retains the FULL frame for late-joiner bootstrap.
+    assert "frames" in poller.last_frame["timeline"]
+
+
+async def test_new_race_resends_full_timeline():
+    """A different race_id resets the strip state — full timeline again."""
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([
+            _racing_frame("race-A", 0.0),
+            _racing_frame("race-B", 0.0),
+        ]),
+        ws_manager=ws,
+    )
+    await poller._poll_once()
+    await poller._poll_once()
+    assert "frames" in ws.messages[0]["data"]["timeline"]
+    assert "frames" in ws.messages[1]["data"]["timeline"]
+