fix(infrastructure): add dynamic CORS origin mapping and preflight handling for admin API endpoints

- Created a new dashboard for NGINX monitoring with panels for status, active connections, request rates, and connection drop ratio.
- Added a Node dashboard to monitor CPU usage, memory usage, disk I/O, and network traffic.
- Introduced a Playout dashboard to track service status, mode, FFmpeg restarts, and scrape duration.
- Implemented a PostgreSQL dashboard featuring active connections, database size, transaction rates, and cache hit ratio.
- Developed a Prometheus dashboard to visualize scrape duration, targets status, and rule evaluation metrics.
- Established a Redis dashboard to monitor connected clients, memory usage, command latency, and keyspace statistics.

.env.example

@@ -8,6 +8,8 @@ R2_SECRET_ACCESS_KEY=your-r2-secret-key
 R2_BUCKET_NAME=linearvoid-media
 R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
 R2_REGION=auto
+R2_KEEP_RUNS=2
+R2_MAX_RETENTION_BYTES=10737418240
 
 # Cloudflare (for custom domain, cache rules, Workers if used)
 CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
@@ -53,8 +55,13 @@ NGINX_PORT=80
 
 # Playout configuration
 PLAYLIST_PATH=/app/playlist/playlist.txt
-HLS_SEGMENT_DURATION=6
-HLS_WINDOW_SIZE=24
+HLS_SEGMENT_DURATION=2
+HLS_WINDOW_SIZE=12
+
+# Shared runtime config (written by chat admin via /api/admin/config, read by playout).
+# Both resolve to the same host file through the ./data/playlist volume.
+CONFIG_PATH=/app/playlist/config.json
+PLAYOUT_CONFIG_PATH=/app/playlist/config.json
 
 # Logging / Monitoring
 LOG_LEVEL=info

.gitea/workflows/cd.yml

@@ -6,12 +6,14 @@
 name: CD
 
 on:
-  push:
-    branches: [main]
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
   workflow_dispatch:
 
 jobs:
   deploy:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
     runs-on: [ubuntu-latest]
     steps:
       - name: Checkout code
@@ -31,15 +33,42 @@ jobs:
       - name: Prepare environment
         run: |
           cat > .env << 'EOF'
+          # Database & Redis
           DATABASE_URL="${{ secrets.DATABASE_URL }}"
           REDIS_URL=redis://redis:6379/0
+
+          # Playout
           PLAYLIST_PATH=/app/playlist/playlist.txt
-          HLS_SEGMENT_DURATION=6
-          HLS_WINDOW_SIZE=24
+          HLS_SEGMENT_DURATION=2
+          HLS_WINDOW_SIZE=12
           LOG_LEVEL=info
+
+          # Cloudflare R2 (required for HLS segment sync)
+          R2_ACCESS_KEY_ID="${{ secrets.R2_ACCESS_KEY_ID }}"
+          R2_SECRET_ACCESS_KEY="${{ secrets.R2_SECRET_ACCESS_KEY }}"
+          R2_BUCKET_NAME="${{ secrets.R2_BUCKET_NAME }}"
+          R2_ENDPOINT="${{ secrets.R2_ENDPOINT }}"
+          R2_REGION=auto
+
+          # Cloudflare
+          CLOUDFLARE_API_TOKEN="${{ secrets.CLOUDFLARE_API_TOKEN }}"
+          CLOUDFLARE_ACCOUNT_ID="${{ secrets.CLOUDFLARE_ACCOUNT_ID }}"
+          MEDIA_DOMAIN=${{ secrets.MEDIA_DOMAIN }}
+
+          # Frontend public URLs
+          VITE_PUBLIC_APP_URL=${{ secrets.VITE_PUBLIC_APP_URL }}
+          VITE_PUBLIC_WS_URL=${{ secrets.VITE_PUBLIC_WS_URL }}
+          VITE_PUBLIC_HLS_URL=${{ secrets.VITE_PUBLIC_HLS_URL }}
+          VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR=${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR }}
+          VITE_PUBLIC_ADMIN_DEFAULT_ROOM=${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_ROOM }}
+          VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT=50
+
+          # Admin auth
           ADMIN_USERNAME="${{ secrets.ADMIN_USERNAME }}"
           ADMIN_PASSWORD="${{ secrets.ADMIN_PASSWORD }}"
           ADMIN_SESSION_TTL_HOURS=12
+
+          # Nginx
           NGINX_PORT=80
           EOF
 
@@ -241,8 +270,8 @@ jobs:
               echo "Playout is healthy"
               break
             fi
-            echo "Playout not ready yet (attempt $i/6), waiting 5s..."
-            sleep 5
+            echo "Playout not ready yet (attempt $i/6), waiting 10s..."
+            sleep 10
           done
           if ! docker exec linearvoid-playout curl -sf http://localhost:8081/health; then
             echo "Playout failed to become healthy after 6 attempts"

.gitea/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
 
       - name: Install Frontend Dependencies
         run: cd frontend && npm ci
@@ -26,6 +26,9 @@ jobs:
       - name: Lint Frontend
         run: cd frontend && npm run lint
 
+      - name: Test Frontend with Coverage
+        run: cd frontend && npm run test:coverage
+
       - name: Build Frontend
         run: cd frontend && npm run build
 

.gitea/workflows/workers-deploy.yml

@@ -0,0 +1,41 @@
+name: Deploy to Cloudflare Workers
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+  workflow_dispatch: {}
+
+jobs:
+  deploy:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: cd frontend && npm ci
+
+      - name: Build
+        env:
+          VITE_PUBLIC_APP_URL: ${{ secrets.VITE_PUBLIC_APP_URL }}
+          VITE_PUBLIC_WS_URL: ${{ secrets.VITE_PUBLIC_WS_URL }}
+          VITE_PUBLIC_HLS_URL: ${{ secrets.VITE_PUBLIC_HLS_URL }}
+          VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR: ${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR }}
+          VITE_PUBLIC_ADMIN_DEFAULT_ROOM: ${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_ROOM }}
+          VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT: "50"
+        run: cd frontend && npm run build
+
+      - name: Deploy to Cloudflare Workers
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          cd frontend
+          npx wrangler deploy

.github/AGENTS.md

@@ -2,10 +2,6 @@
 
 Agents instructions for the linearvoid project.
 
-## Output
-
-- use /caveman skill, latest version from <https://github.com/JuliusBrussee/caveman> is <https://github.com/JuliusBrussee/caveman/tree/main/skills/caveman>
-
 ## General Guidelines
 
 - Use the architecture documentation (arc42 template and ADRs in `docs`) as the source of truth for design decisions.
@@ -14,9 +10,28 @@ Agents instructions for the linearvoid project.
 
 ## Task Management
 
-- Plan any task in the `TODO.md` file with clear steps and mark them as completed when done. Move completed sections to DONE.md. Write entry in root `CHANGELOG.md` for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the `TODO.md` file.
+- Plan any task in the `.github/instructions/TODO.md` file with clear steps and mark them as completed when done. Move completed sections to `.github/instructions/DONE.md`. Write entry in root `CHANGELOG.md` for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the `TODO.md` file.
 - Before taking any action except for planning and writing `TODO.md`, always ask user for confirmation, accept `go`, `ok`, `yes`, `next`, or `continue` to proceed. If the user says `no`, `stop`, or `cancel`, abort the action and return to planning.
 
+### Required tracking files — update at every development step
+
+These files must be kept current with every change. Do not let them drift.
+
+| File                              | Purpose                                       | When to update                                                     |
+| --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
+| `.github/instructions/TODO.md`    | Active implementation plan with checkboxes    | Mark items done as they complete; add new items when scope expands |
+| `.github/instructions/BACKLOG.md` | Deferred, manual, and operational tasks       | Sync whenever TODO items complete or new gaps are identified       |
+| `.github/instructions/DONE.md`    | Archive of completed TODO sections            | Move completed sections here from TODO.md                          |
+| `.github/MEMORY.md`               | Session memory — what was done, when, and why | Append dated entry after each meaningful batch of changes          |
+| `CHANGELOG.md`                    | User-facing release notes                     | Add entry when a phase or significant feature completes            |
+| `docs/STREAMING.md`               | Streaming pipeline contract                   | Update when playout, HLS, or caching behavior changes              |
+| `docs/DEPLOYMENT.md`              | Deploy and infrastructure procedures          | Update when pipeline, topology, or provisioning changes            |
+| `docs/SETUP.md`                   | Environment and onboarding guide              | Update when prerequisites, `.env`, or setup steps change           |
+| `docs/MONITORING.md`              | Observability reference                       | Update when metrics, alerts, or dashboards change                  |
+| `docs/API.md`                     | API contract                                  | Update when endpoints, status codes, or rate limits change         |
+| `docs/SECURITY.md`                | Security posture                              | Update when auth, TLS, or rate limiting changes                    |
+| `docs/operations/*.md`            | Runbooks, checklists, how-to guides           | Keep aligned with actual procedures and dashboard URLs             |
+
 ## Security & Secrets Protection
 
 - **Never commit raw secrets or credentials** to the repository.

.github/MEMORY.md

@@ -0,0 +1,154 @@
+# MEMORY
+
+## 2026-08-07
+
+- Completed runtime validation section from TODO.
+- Runtime video normalization tests executed in running `linearvoid-playout` container using ffmpeg/ffprobe.
+- Verified normalized outputs for MOV, MKV, VFR, and 5.1 inputs: `h264`, `yuv420p`, `30/1`, `aac`, `48000`, `2 channels`.
+- Concat continuity check passed with `CONCAT_OK`; output duration `25.344667` seconds.
+- Responsive viewport test on live viewer (`390x844`, `412x915`) detected 8px horizontal overflow from `100vw` usage in viewer container styles.
+- Fixed overflow in source by changing `.lv-body` and `.viewer-shell` width from `100vw` to `100%` in `frontend/src/style.css`.
+- Redis restart test:
+  - Admin session endpoint returned 200 before and after Redis restart.
+  - Presence key survived Redis restart in test-lab configuration.
+  - Redis health returned to `healthy` post-restart.
+- Files changed:
+  - `.github/instructions/TODO.md`
+  - `.github/instructions/DONE.md`
+  - `frontend/src/style.css`
+  - `CHANGELOG.md`
+
+## 2026-08-07 (continued)
+
+- Completed documentation half of recovery runbook TODO item.
+- Expanded `docs/incident-runbook.md` with quarterly DR drill: prerequisites, outage simulation, restore validation, pass/fail criteria, and evidence template.
+- Split TODO item into:
+  - documented drill (`[x]`)
+  - manual rehearsal execution (`[ ]`)
+- Updated `CHANGELOG.md` with incident runbook drill documentation entry.
+
+## 2026-08-07 (continued 2)
+
+- Added manual operations checklist `docs/operations/cloudflare-uptimerobot-checklist.md` for Cloudflare + UptimeRobot task execution and evidence capture.
+- Linked checklist from `SETUP.md` Cloudflare section and TODO manual sections.
+- Did not mark manual dashboard items complete; checklist is preparation only.
+
+## 2026-08-07 (continued 3)
+
+- Added `docs/operations/scaling-performance-playbook.md` covering manifest TTL tuning, TTFB baseline method, WebSocket/API benchmarking approach, cache ratio tracking, capacity triggers, and Phase 2/3 plans.
+- Updated TODO and BACKLOG to mark playbook creation done while keeping execution/measurement tasks pending.
+- Linked scaling playbook in `README.md` resources.
+
+## 2026-08-09
+
+- Added WebSocket benchmark summary helper `scripts/loadtest/summarize-artillery.ps1`.
+- Updated `scripts/loadtest/run-loadtests.ps1` to auto-generate `ws-chat-summary.txt` for `ws` and `all` scenarios.
+- Updated `scripts/loadtest/summarize-k6.ps1` to produce pipeline-friendly output and integrated automatic `admin-api-endpoint-summary.txt` generation.
+- Expanded `scripts/loadtest/README.md` with PowerShell-first artifact capture and helper usage for both ws and admin scenarios.
+- Updated `.gitignore` to ignore loadtest artifacts (`artifacts/` and `scripts/loadtest/artifacts/`).
+- Added artifact-to-worksheet field mapping section in `docs/operations/scaling-performance-playbook.md` so ws/admin worksheet entries map directly to generated summary files.
+- Updated `docs/DEVELOPMENT.md` and `.github/instructions/TODO.md` to mark ws/admin benchmark scaffolding complete while live benchmark execution remains pending.
+- Added `CHANGELOG.md` entry `1.0.10` summarizing loadtest helper automation and playbook mapping updates.
+
+## 2026-08-09 (continued)
+
+- Completed Phase 1 (test fixtures): documented ffmpeg fixture-generation commands in `playlist_test.go` header comments (valid_720p30, invalid_h265, invalid_24fps).
+- Completed Phase 4 (R2 integration):
+  - Enhanced `SyncToR2` in `playlist.go` to set CacheControl + ContentType based on file extension:
+    - `.m4s`, `.ts`, `.mp4`, `.m4a` -> `public, max-age=31536000, immutable` + `video/MP2T`
+    - `.m3u8` -> `public, max-age=2` + `application/vnd.apple.mpegurl`
+    - unknown extension -> no cache headers
+  - Added three tests: `TestSyncToR2` (segment upload with cache verification), `TestSyncToR2_ManifestCacheHeaders` (manifest upload), `TestSyncToR2_NoCacheHeadersForUnknownExt` (unknown extension).
+  - All 17 playout tests pass (16 pass, 1 pre-existing skip).
+- Updated TODO.md: Phase 1 marked complete, Phase 4 partially complete (edge cache hit/miss remains manual).
+- Updated DEVELOPMENT.md: Test Fixtures marked complete, R2 Integration Test marked partially complete.
+
+## 2026-08-09 (continued 2)
+
+- Completed Phase 2 chat tests in `frontend/src/main.test.ts`:
+  - Presence updates: join/leave system messages add and remove users from presence list, sorted rendering.
+  - Private DM flow: togglePrivateDM creates correct dm: room name from sorted usernames.
+  - Message rendering: system messages, self messages (message-self), and other-user messages (message-other) all render correctly.
+  - Total frontend tests: 27 passing (2 test files).
+- Marked Phase 4 "Document stubs/mocks" done (putObject injection pattern).
+- Updated TODO.md: Phase 2 chat tests checked, Phase 4 stubs checked.
+- Updated DEVELOPMENT.md: User Frontend Tests marked partially complete, R2 stubs checked.
+- Updated CHANGELOG.md with Phase 2 presence/DM/message tests.
+
+## 2026-08-09 (continued 3)
+
+- Completed Phase 3 admin frontend tests in `frontend/src/admin.test.ts`:
+  - Exported `savePlaylist` and `renderPlaylistSortable` from `admin.ts`.
+  - Added playlist save test (verifies PUT /api/admin/playlist with JSON body).
+  - Added playlist save error handling test (verifies failure status).
+  - Added sortable rendering test (verifies index, paths, remove buttons, comment/blank line skip).
+  - Total frontend tests: 31 passing (2 test files).
+- Updated TODO.md: Phase 3 playlist/dashboard/API integration all checked.
+- Updated DEVELOPMENT.md: Admin Frontend Tests marked partially complete.
+
+## 2026-08-10 (continued 2)
+
+- Implemented STREAMING.md production-readiness gaps from plan `.hermes/plans/2026-08-10_164500-production-readiness.md`:
+  - **Task 1-2**: Added `runID` (ISO timestamp format) and monotonic `segSequence` for globally unique segment naming (`r-{ISOTIME}/seg-{seq}.m4s`). Replaced `strftime` pattern with run ID-based path.
+  - **Task 2**: Added `watchAndPublishSegments` using `fsnotify` for real-time per-segment R2 upload (~7s delay). Previously `syncLatestToR2()` only ran after FFmpeg exit.
+  - **Task 3**: Added `publishManifest` with atomic `CopyObject` (temp key → final key) to prevent manifest referencing unconfirmed segments.
+  - **Task 4**: Updated `manifestCacheControl` from `"public, max-age=2"` to `"public, max-age=1, s-maxage=2, must-revalidate"` per STREAMING.md.
+  - **Task 5**: Added `hls.on(Hls.Events.ERROR)` handler in `main.ts` with bounded retries (5x), exponential backoff (2s→32s), reconnecting overlay (spinner + text). Added `showReconnecting`/`hideReconnecting` functions.
+  - **Task 6**: Enriched `HealthHandler` with `run_id`, `active_item`, `playlist_revision`, `last_segment_seq`, `last_r2_pub`, `consecutive_failures`. Added "unhealthy" status when R2 publish is stale (>12s).
+- Files changed: `backend/playout/src/playlist.go`, `playlist_test.go`, `go.mod`, `frontend/src/main.ts`, `main.test.ts`, `style.css`, `index.html`.
+- Updated `.github/instructions/TODO.md`, `BACKLOG.md`, `MEMORY.md`, `DONE.md`.
+- Remaining: CORS on media.linearvoid.tv (Cloudflare R2 config, infrastructure).
+
+## 2026-08-10 (continued 3)
+
+- Completed Phase 2 (viewer) + Phase 3 (admin) responsive/accessibility tests:
+  - 5 viewer accessibility tests: video controls/attributes, chat panel aria-labels, chat toggle aria-expanded, message input label, reconnecting overlay aria-live/role.
+  - 3 viewer responsive tests: chat-collapsed toggle, CSS grid layout detection, now-playing aria-live.
+  - 3 admin accessibility tests: nav aria-label, active tab aria-current, nav button focusability.
+  - 2 admin responsive tests: tab content visibility, essential tab presence.
+  - Total: 45 frontend tests passing (2 test files).
+- Added coverage reporting: `vitest.config.ts` with v8 provider, thresholds at 20/15/15/20 (statements/branches/functions/lines).
+- Added `test:coverage` script to `package.json`.
+- Fixed CI: bumped Node from 20 to 22 in `ci.yml` and `workers-deploy.yml` (jsdom@30 requires Node 22+). Added `engines` to `package.json`.
+- Updated AGENTS.md: added Required tracking files table with 13 docs and update cadence.
+- All Go vet, Go tests, frontend test:coverage passing.
+- CORS on media.linearvoid.tv remains the only streaming pipeline gap (Cloudflare R2 config, not code).
+
+## 2026-08-10 (continued 4)
+
+- Verified all test suites pass after streaming pipeline implementation:
+  - Playout: `go mod tidy` (added fsnotify v1.8.0) → all tests pass
+  - Chat: 7 packages pass (go vet + go test)
+  - Frontend: 45 tests pass (2 files), test:coverage meets thresholds (22.92% / 18.44% / 19.01% / 25.42%)
+- Edge cache validation script `scripts/validate-edge-cache.sh` exists.
+- Remaining: CORS on media.linearvoid.tv (Cloudflare R2 bucket CORS config, not a code change). Phases 5-7 are manual/infrastructure only (Cloudflare dashboard, Hetzner provisioning, live benchmarks).
+
+## 2026-08-11
+
+- Consolidated all development tasks from `DEVELOPMENT.md` and `.github/instructions/TODO.md` into `.github/instructions/BACKLOG.md` as the single source of truth. `DEVELOPMENT.md` now obsolete and removed. `TODO.md` references `BACKLOG.md` and `DONE.md`.
+- Fixed R2 endpoint validation in playout service (`backend/playout/src/playlist.go`):
+  - Added `isR2Configured()` checking all four required env vars (`R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`).
+  - `initR2Client()` now returns a clear error if R2 is not configured instead of creating an S3 client with an empty endpoint.
+  - Segment watcher (`watchAndPublishSegments`), `syncLatestToR2()`, and `publishManifest()` are now guarded by `r2Client != nil` — no error spam when R2 is unavailable.
+  - Playout gracefully degrades: local HLS via nginx works without R2.
+- Updated `.gitea/workflows/cd.yml` "Prepare environment" step to include all R2* variables sourced from Gitea secrets (`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_ENDPOINT`, `R2_ADMIN*\*`), Cloudflare variables (`CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`), and frontend public URL variables.
+- Updated `docs/DEPLOYMENT.md` "Environment File" section: replaced vague "Cloudflare/R2 variables" bullet with explicit variable lists and added a new "Gitea Secrets" table documenting all 15 required secrets.
+- All playout tests pass (20 tests), `go vet` clean.
+
+## 2026-08-13
+
+- Completed all remaining enhancement tasks (only manual/infrastructure phases left):
+  - **Playout**: automatic media normalization on upload (`media.NormalizeVideo`, `*.normalized.mp4`, statuses `ready`/`needs_normalization`/`normalizing`/`normalization_failed`, `POST /api/admin/media/{id}/normalize`); R2 segment retention (`cleanupOldRuns`, keep last `R2_KEEP_RUNS` runs, `R2_MAX_RETENTION_BYTES` cap); seamless looping (playlist SHA-256 fingerprint + `-start_number`); single `start-playout.sh` entrypoint + `-validate` mode; loop/cleanup metrics.
+  - **Application configuration**: thread-safe JSON runtime config store (`backend/chat/src/config/runtime.go`) shared with playout via `/app/playlist/config.json`; `GET/PUT /api/admin/config`; admin UI config form.
+  - **Matomo analytics**: public `GET /api/matomo` + viewer pageview snippet in `index.html`.
+  - **Chat user accounts**: register/login/logout/session endpoints, bcrypt hashing, `linearvoid_user_session` cookie, viewer sign-in UI.
+  - **DM history & search**: `GET /api/dm/history` (paginated) + `GET /api/dm/search` + DM search UI.
+  - **Chat UI**: typing indicator, user-list toggle, media status badges, "Add to playlist" gated to `ready`.
+  - **Prometheus TSDB retention**: `--storage.tsdb.retention.time=30d` + `--storage.tsdb.retention.size=15GB` in both compose files; alert rule count corrected 8 → 10.
+- Updated `docs/architecture/README.md` to reflect all `[Unreleased]` changes (normalization, looping, retention, runtime config, Matomo, user accounts, DM history/search, new API endpoints, module tables).
+- Released **1.0.13**: promoted changelog, bumped version, tagged and pushed.
+- Extended frontend test coverage: added `counter.test.ts`, reconnecting/typing/auth/websocket tests, admin failure + status-badge tests → 56 tests; statements 19.89% → 28.58% (CI coverage threshold passing).
+- Fixed Go test data race in `TestHandleAdminMediaByID_Normalize` (waits for async normalization goroutine) + shared in-memory SQLite via `SetMaxOpenConns(1)`.
+- Fixed viewer crash: `index.html` was missing the `#messages` chat container (stray `</section>`); restored structure + made `addMessage` defensive.
+- Set `Doto` as the body font (`--font-body`) and added Google Fonts links to admin + login pages.
+- Files changed: across `backend/chat`, `backend/playout`, `frontend`, `docs`, `docker-compose*.yml`, `.github/instructions/*`.

.github/instructions/BACKLOG.md

@@ -0,0 +1,136 @@
+# BACKLOG
+
+> All current work is planned in [TODO](./TODO.md) (2026-08-13). This file lists backlog items; new unplanned work is added here.
+
+## Setup phases remaining
+
+### Phase 5: complete manual Cloudflare and external-service setup
+
+- [ ] Apply Cloudflare Workers, Tiered Cache, WAF, rate limiting, and HTTPS/HSTS settings in the dashboard
+- [ ] Cloudflare Workers: link custom domain and cut over frontend hosting
+- [ ] Enable Smart Tiered Cache; validate `Cf-Cache-Status: HIT` from upper tier
+- [ ] WAF: enable OWASP Managed Ruleset (Simulate → review 48h → Block), enable Bot Fight Mode
+- [ ] Rate limiting: `/api/admin/login` + `/api/admin/*` → 10 req/10s per IP, Challenge action
+- [ ] HTTPS/WSS: Always Use HTTPS, HSTS max-age=31536000 includeSubDomains preload, min TLS 1.2; enforce at edge and origin
+- [ ] UptimeRobot: add HTTP monitor for `https://linearvoid.tv/health` (5min interval)
+- [ ] UptimeRobot: add keyword monitor for `https://linearvoid.tv/hls/playlist.m3u8` (keyword `#EXTM3U`, 5min)
+- [ ] UptimeRobot: alert on 2 consecutive failures via email + Discord/Slack webhook
+- [ ] Capture evidence in `docs/operations/cloudflare-uptimerobot-checklist.md`
+
+### Phase 6: rehearse production deployment end to end
+
+- [ ] Provision Hetzner CX22 (2 vCPU, 4 GB, 40 GB) in Ashburn VA, Ubuntu 24.04
+- [ ] Install Docker Engine + Compose plugin; open firewall: 80/443 public, 2375 runner-only
+- [ ] Configure Docker daemon for remote TLS access (`-H tcp://0.0.0.0:2376` with certs)
+- [ ] Create `/srv/linearvoid/data/{playlist,media,hls,chat,slate}` directories
+- [ ] Add `CI_PROD_*` secrets to Gitea (DOCKER_HOST, R2 keys, admin password, DB password, Grafana password)
+- [ ] Trigger CD workflow with `DOCKER_HOST` pointing to Hetzner IP
+- [ ] Verify all 11 containers healthy: `/health`, `/hls/playlist.m3u8`, WebSocket
+- [ ] Update Cloudflare A record `linearvoid.tv` → Hetzner IP, SSL Full (strict); test HTTPS + WSS
+- [ ] Smoke test: viewer SPA loads, HLS plays, chat connects, admin login → upload → playlist → playout
+- [ ] Set up Prometheus alerting notifications + UptimeRobot on production URL
+- [ ] Run `scripts/backup-db.sh` + `scripts/verify-backups.sh` on production host
+- [ ] Document production IP, SSH access, rollback procedure, scaling thresholds
+
+### Phase 7: baseline scaling and performance
+
+- [ ] Execute WebSocket load tests — ramp 10→100→500→1000 connections; measure p95 latency + errors
+- [ ] Execute admin API benchmarks — `wrk`/`k6` against `/api/admin/*`; target p95 <1s
+- [ ] Measure manifest TTFB and cache-hit distribution from multiple US regions (WebPageTest 3+ regions, <4s warm cache)
+- [ ] Tune manifest TTL to 0.5× segment duration; validate `Cf-Cache-Status` distribution
+- [ ] Track cache-hit ratio and R2 ops in production (Cloudflare GraphQL → Grafana panel, alert <90%)
+- [ ] Capacity triggers: Prometheus rules for cache-miss >10%/15min, CPU >80%/10min
+- [ ] Plan Phase 2 service separation (playout CPU, chat latency, DB state, monitoring)
+- [ ] Plan Phase 3 multi-origin resilience (second Hetzner location, warm standby, DNS failover, DB/Redis replication)
+
+### Phase 8: close out remaining test and validation gaps
+
+- [ ] Admin frontend: user moderation tools tests (mute/ban/report, view moderation logs)
+- [ ] Frontend: coverage for all critical user + admin components and interactions
+- [ ] Frontend: document test cases and expected outcomes
+- [ ] Backend R2: test retrieval of segments/manifests via Cloudflare edge
+- [ ] Backend R2: validate edge cache hit/miss behavior with repeat requests (`scripts/validate-edge-cache.sh`)
+
+### Playout
+
+- [ ] Configure an R2 lifecycle rule on the `hls/` prefix as defense-in-depth (manual)
+- [ ] Full-loop E2E (2-file playlist, assert `Looping...` with no `CRASHED` across the boundary) — manual via `scripts/test-playout-e2e.sh`
+
+## Cloudflare Configuration
+
+### DNS & Workers
+
+- [ ] Cloudflare Workers: link custom domain (manual)
+- [ ] Create Cloudflare Worker and cut over frontend hosting (manual)
+
+### Security & TLS
+
+- [ ] Enable Tiered Cache, WAF, rate limiting (manual)
+- [ ] Tiered Cache: enable Smart Tiered Cache, validate `Cf-Cache-Status: HIT` from upper tier
+- [ ] WAF: enable OWASP Managed Ruleset, set to Simulate → review 48h → Block, enable Bot Fight Mode
+- [ ] Rate limiting: `/api/admin/login` + `/api/admin/*` → 10 req/10s per IP, Challenge action
+- [ ] HTTPS/WSS: Always Use HTTPS, HSTS max-age=31536000 includeSubDomains preload, min TLS 1.2
+- [ ] HTTPS/WSS: enforce at edge (Cloudflare) and origin (nginx), redirect HTTP → HTTPS
+
+## Monitoring & Observability
+
+### External Monitoring
+
+- [ ] Set up UptimeRobot external monitoring
+- [ ] UptimeRobot: add HTTP monitor for `https://linearvoid.tv/health` (5min interval)
+- [ ] UptimeRobot: add keyword monitor for `https://linearvoid.tv/hls/playlist.m3u8` (keyword: `#EXTM3U`, 5min)
+- [ ] Alert on 2 consecutive failures, notify via email + Discord/Slack webhook
+
+## External Services
+
+> Evidence tracker: `docs/operations/cloudflare-uptimerobot-checklist.md`
+
+- [ ] UptimeRobot: add HTTP monitor for `https://linearvoid.tv/health` (5min interval)
+- [ ] UptimeRobot: add keyword monitor for `https://linearvoid.tv/hls/playlist.m3u8` (keyword: `#EXTM3U`, 5min)
+- [ ] Alert on 2 consecutive failures, notify via email + Discord/Slack webhook
+
+## Production Deployment
+
+### Host Provisioning (Hetzner — not provisioned)
+
+- [ ] Provision Hetzner CX22 (2 vCPU, 4 GB, 40 GB) in Ashburn VA, Ubuntu 24.04
+- [ ] Install Docker Engine + Compose plugin, open firewall: 80/443 (public), 2375 (runner IP only)
+- [ ] Configure Docker daemon for remote TLS access (`-H tcp://0.0.0.0:2376` with certs)
+- [ ] Create `/srv/linearvoid/data/{playlist,media,hls,chat,slate}` directories
+
+### CI/CD & Secrets
+
+- [ ] Add `CI_PROD_*` secrets to Gitea: DOCKER_HOST, R2 keys, admin password, DB password, Grafana password
+- [ ] Trigger CD workflow with `DOCKER_HOST` pointing to Hetzner IP
+
+### Smoke Test & Cutover
+
+- [ ] Verify all 11 containers start healthy, check `/health`, `/hls/playlist.m3u8`, WebSocket
+- [ ] Update Cloudflare A record `linearvoid.tv` → Hetzner IP, SSL Full (strict), test HTTPS + WSS
+- [ ] Smoke test: viewer SPA loads, HLS plays, chat connects, admin login → upload → playlist → playout
+
+### Production Operations
+
+- [ ] Set up Prometheus alerting notifications + UptimeRobot on production URL
+- [ ] Run `scripts/backup-db.sh` + `scripts/verify-backups.sh` on production host
+- [ ] Document production IP, SSH access, rollback procedure, scaling thresholds
+
+## Scaling & Performance
+
+### Load Testing
+
+- [ ] Execute WebSocket load tests with real infrastructure — ramp 10→100→500→1000 connections, measure p95 latency + errors
+- [ ] Execute admin API benchmarks with real infrastructure — `wrk`/`k6` against `/api/admin/*`, target p95 <1s
+
+### Cache & TTFB Optimization
+
+- [ ] Optimize segment immutability and manifest TTL for cache efficiency
+- [ ] Tune manifest TTL: measure `Cf-Cache-Status` distribution, adjust to 0.5× segment duration
+- [ ] Measure playback TTFB from multiple US regions — WebPageTest from 3+ regions, target <4s warm cache
+- [ ] Track cache hit ratio and R2 ops in production — Cloudflare GraphQL → Grafana panel, alert <90%
+
+### Capacity & Future Planning
+
+- [ ] Capacity triggers: Prometheus rules for cache-miss >10%/15min, CPU >80%/10min
+- [ ] Plan Phase 2 service separation — document boundaries (playout CPU, chat latency, DB state, monitoring), estimate per-service resources
+- [ ] Plan Phase 3 multi-origin resilience — research second Hetzner location, design warm standby + DNS failover + DB/Redis replication

.github/instructions/DONE.md

@@ -0,0 +1,39 @@
+# DONE
+
+> Completed tasks from [TODO](./TODO.md). Product, feature, and release history lives in [CHANGELOG](./CHANGELOG.md); this file keeps only engineering and ops notes not captured there.
+
+## Test infrastructure & refactors (2026-08-07)
+
+- Chat service `main.go` split into 8 packages (config, auth, db, handlers, ws, media, ratelimit, metrics); `db.RedisClient` + `db.PubSub` interfaces added for mocking.
+- 78 tests total (Go + frontend), all passing. Coverage: auth 97.8%, config 100%, metrics 100%, ratelimit 90.3%, ws 79.6%, handlers 47.2%, media 36.8%, db 14.3%.
+- Playout: 12 tests. Frontend: vitest + jsdom, 6 user + 5 admin smoke tests.
+- CI: `go test -race -cover` with a 50% coverage threshold; SQLite switched to pure-Go `github.com/glebarez/sqlite` (CGO-free, works on Windows).
+- Frontend coverage enforcement: vitest v8 provider, 40% statements/lines + 30% branches/functions thresholds, `test:coverage` script + CI step.
+
+## Backups
+
+- `scripts/backup-db.sh` (daily pg_dump → R2, 14-day retention), `scripts/backup-weekly.sh` (weekly full dump + integrity check, 8-week retention), `scripts/verify-backups.sh` (download → temp Postgres → restore + row counts).
+
+## Gitea self-hosting migration
+
+- Migrated repo + CI/CD from GitHub to Gitea Actions (`git.allucanget.biz/zwitschi/linearvoid`): self-hosted runner, Container Registry convention `git.allucanget.biz/zwitschi/linearvoid/<service>:<tag>`, secrets renamed `GITEA_*` → `CI_*`.
+
+## Streaming pipeline gaps (2026-08-10)
+
+- Continuous R2 sync via `fsnotify` (`watchAndPublishSegments`, ~7s delay); run-ID + monotonic segment naming (`r-{ISOTIME}/seg-{seq}.m4s`); atomic manifest publication (upload `.tmp` → `CopyObject`); enriched `/health` (run_id, active_item, playlist_revision, last_segment_seq, last_r2_pub, consecutive_failures); player error recovery (5 retries, 2s→32s exponential backoff, reconnecting overlay).
+- CORS on `media.linearvoid.tv` remains infrastructure-only (Cloudflare R2 config, not code).
+
+## Bug fixes not in CHANGELOG
+
+- **2026-08-13 viewer crash**: `index.html` was missing the `#messages` container, so `addMessage` threw `Cannot read properties of null (reading 'appendChild')` on WebSocket open/message. Restored the chat panel structure and made `addMessage` defensive.
+- **2026-08-15 chat reconnect loop**: after a registered user logged in, the chat panel repeatedly filled with old messages. `connectWebSocket` left the replaced socket's `onclose` handler attached, so each intentional reconnect scheduled another reconnect and every connection re-pulled the room's 50-message history on a 3s loop. Fixed by detaching the old socket's `onclose` before closing and guarding the handler against stale sockets. Regression test added; `npm --prefix frontend test` → 58 tests passing.
+
+## Chat improvements
+
+- Manual smoke: viewer join/leave shows a 3s flash (not a chat row); reconnect <5s shows no duplicate; admin chat-log table has no system rows
+
+## Playout improvements
+
+- Test in Firefox: live playback, rebuffer/recovery, chat sync; record quirks in `docs/STREAMING.md`
+- Rebuild + run playout; confirm `playlist.m3u8` lists ~12 segments at 2s each
+- Manual: verify viewer latency and cache-hit behavior after the change

.github/instructions/TODO.md

@@ -0,0 +1,30 @@
+# TODO
+
+> Completed tasks moved to [DONE](./DONE.md). Remaining tasks in [BACKLOG](./BACKLOG.md).
+
+## Cloudflare Workers
+
+- [x] Adjust `frontend/src/main.ts` to use `VITE_PUBLIC_APP_URL` for API requests instead of hardcoded `/api/...` paths.
+- [x] Adjust `frontend/src/main.ts` to use `VITE_PUBLIC_WS_URL` for WebSocket connections instead of hardcoded `wss://...` paths.
+
+## Frontend Tests
+
+### User Frontend
+
+- [ ] Test coverage for all critical frontend components and interactions
+- [ ] Add code coverage reporting and enforce minimum coverage threshold in CI/CD pipeline
+- [ ] Document test cases and expected outcomes
+
+### Admin Frontend
+
+- [ ] Test coverage for all critical admin UI components and interactions
+- [ ] Add code coverage reporting and enforce minimum coverage threshold in CI/CD pipeline
+- [ ] Document test cases and expected outcomes
+
+## Backend Integration Tests
+
+### Cloudflare R2
+
+- [ ] Test retrieval of segments and manifests from R2 via Cloudflare edge
+- [ ] Validate cache hit/miss behavior and performance metrics
+- [ ] Validate edge cache hit/miss behavior with repeat requests — script `scripts/validate-edge-cache.sh` created

.gitignore

@@ -87,10 +87,6 @@ Thumbs.db
 *.tfstate.backup
 .terraform/
 
-# Agent / Tool files
-.github/agents/
-.github/instructions/
-.github/MEMORY.md
 
 # Temporary architecture artifacts
 **/*.tmp

CHANGELOG.md

@@ -2,6 +2,73 @@
 
 <!-- markdownlint-disable MD024 -->
 
+## [Unreleased]
+
+### Added
+
+- **Transient presence flash**: Join/leave announcements now appear as a 3-second flash at the top of the chat panel (`#chat-flash`) with a fade-out, instead of permanent chat rows. Presence indicators still update from the same events.
+
+### Changed
+
+- **System messages no longer persisted**: The chat backend no longer stores `system`-type messages; chat history and the admin chat-log table only contain real chat messages (moderation actions remain in the audit log).
+- **Reconnect grace period**: Disconnects schedule a delayed "left" announcement (5s); a reconnect within 5s cancels it and skips "joined", eliminating join/leave spam on brief reconnects.
+- **HLS segment duration 2s**: Default `HLS_SEGMENT_DURATION` changed from 6 to 2 and `HLS_WINDOW_SIZE` from 24 to 12 (2s × 12 = 24s live window), reducing end-to-end latency; the 2s GOP was already in place.
+- **Chat font sizing**: `.message-text` set to `0.95rem` (slightly smaller than the default, larger than the `0.83rem` system/flash text).
+- **R2 retention by run count + size**: Playout now keeps the newest `R2_KEEP_RUNS` run folders (default 2) and enforces an `R2_MAX_RETENTION_BYTES` cap (default 10 GiB), replacing the old 24h time-based `R2_SEGMENT_RETENTION_HOURS` cleanup. Cleanup runs after each new run plus an hourly backstop, and never deletes the live manifest. Adds `linearvoid_playout_r2_runs_retained` and `linearvoid_playout_r2_bytes_retained` gauges.
+- **Cloudflare Workers frontend hosting**: Replaced Cloudflare Pages with a Cloudflare Worker (`linearvoid-frontend`) that serves the static SPA via Workers Static Assets. Added `frontend/wrangler.toml` and renamed the deploy workflow to `.gitea/workflows/workers-deploy.yml` (builds the SPA and runs `npx wrangler deploy`). Architecture, setup/deployment, and ops documentation updated from Pages to Workers.
+
+### Fixed
+
+- **Login/register cross-origin API URLs**: `submitAuth` in `frontend/src/main.ts` now prefixes `/api/auth/login` and `/api/auth/register` with `VITE_PUBLIC_APP_URL` (falling back to same-origin), matching the other API calls so the Workers-served SPA reaches the app origin instead of a same-origin path.
+
+### Tests
+
+- WebSocket: `TestHub_Broadcast_SystemNotPersisted`, `TestHub_ReconnectGracePeriod`.
+- Handlers: `TestHandleAdminChatLog_ExcludesSystem`.
+- Frontend: `presence flash` test.
+- Playout: `TestCleanupOldRuns`, `TestCleanupOldRuns_SizeCap`, `TestR2KeepRuns`, `TestR2MaxRetentionBytes`, `TestR2RunFromKey`.
+
+## [1.0.13] - 2026-08-13
+
+### Added
+
+- **Automatic media normalization on upload**: Chat backend auto-transcodes non-conforming uploads. New `media.NormalizeVideo` wraps ffmpeg with the Linear Void profile (H.264/AAC, 30fps, 2s keyframes, yuv420p, 48kHz stereo), re-verifies output with ffprobe, and writes `*.normalized.mp4`. Media records gain `normalizing` / `normalization_failed` statuses; `POST /api/admin/media/{id}/normalize` re-triggers manually. Admin UI shows a "Normalize" action with status polling.
+- **R2 segment retention**: Playout `cleanupOldSegments` deletes `hls/r-*/*` objects older than `R2_SEGMENT_RETENTION_HOURS` (default 24h), run hourly + at startup, never touching the live manifest. Exposes `linearvoid_playout_r2_cleanup_objects_total` metric. `.env.example` adds `R2_SEGMENT_RETENTION_HOURS`.
+- **Playout loop metrics**: `linearvoid_playout_loops_total` (clean completions) and `linearvoid_playout_run_duration_seconds` (last run duration).
+- **Runtime configuration store**: Thread-safe, JSON-persisted runtime config (`HLS_SEGMENT_DURATION`, `HLS_WINDOW_SIZE`, `MATOMO_URL`, `MATOMO_SITE_ID`) with typed getters/setters + validation, editable via `GET/PUT /api/admin/config`. Playout reads the shared `config.json` as env fallback.
+- **Matomo analytics**: Viewer pageview snippet in `index.html` driven by the public `GET /api/matomo` endpoint.
+- **Chat user accounts**: Register/login/logout (`POST /api/auth/register`, `/login`, `/logout`, `GET /api/auth/session`), bcrypt password hashing, `linearvoid_user_session` cookie, and a viewer sign-in UI.
+- **Private DM history & search**: `GET /api/dm/history` (paginated) and `GET /api/dm/search`, with a DM search UI in the viewer.
+- **Chat UI polish**: Typing indicator, user-list toggle, media status badges, and an "Add to playlist" action gated to `ready` media.
+
+### Changed
+
+- **Playout seamless looping**: `main()` now only resets HLS output when the playlist changed (SHA-256 `playlistRevision`), on crash/slate recovery, or first run; otherwise it continues segment numbering via `-start_number` and prunes stale segments. Eliminates the viewer gap on clean playlist loops.
+- **Single playout entrypoint**: `start-playout.sh` now runs `/app/playlist-manager -validate` then `exec`s the Go binary, removing the duplicate shell ffmpeg loop. Added a `-validate` mode to `main()`.
+- **Admin media library**: Shows status badges (`ready`/`needs_normalization`/`normalizing`/`failed`) and only offers "Add to playlist" for `ready` media; playlist entries show per-item status badges.
+- **Prometheus TSDB retention**: The `prometheus` service now sets `--storage.tsdb.retention.time=30d` and `--storage.tsdb.retention.size=15GB` (in both `docker-compose.yml` and `docker-compose.prod.yml`), so metrics older than 30 days are deleted.
+
+### Tests
+
+- Media: `TestNormalizationArgs`, `TestNormalizeVideo_FFmpegError`.
+- Handlers: `TestNormalizeMediaRecord_Success`, `TestNormalizeMediaRecord_Failure`, `TestHandleAdminMediaByID_Normalize`.
+- Playout: `TestCleanupOldSegments`, `TestR2SegmentRetentionHours`, `TestPlaylistFingerprint`, `TestHLSNextStartNumber`, `TestLoadSharedHLSConfig`.
+- Config: `runtime_test.go` (get/set, persist/reload, env fallback, validation).
+- Auth: `TestUserSessionStore`.
+- Handlers: config GET/PUT + validation, DM history/search, user register/login/session.
+
+## [1.0.12] - 2026-08-11
+
+### Changed
+
+- **Task tracking consolidated**: Removed `DEVELOPMENT.md` and moved all development tasks to `.github/instructions/BACKLOG.md` as the single source of truth. `TODO.md` updated to reference `BACKLOG.md` and `DONE.md`.
+
+### Fixed
+
+- **Playout R2 endpoint validation**: `initR2Client()` now validates all required R2 environment variables (`R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`) before creating the S3 client. Previously, an empty `R2_ENDPOINT` caused cryptic `Custom endpoint '' was not a valid URI` errors on every segment upload attempt. Playout now gracefully degrades when R2 is not configured — local HLS via nginx continues to work.
+- **CD workflow missing R2 secrets**: `.gitea/workflows/cd.yml` "Prepare environment" step now injects all R2\_ variables (`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_ENDPOINT`, plus admin variants) from Gitea secrets. Previously the generated `.env` was missing R2 entirely, causing the playout container to start with an empty endpoint.
+- **Deployment docs**: `docs/DEPLOYMENT.md` now includes explicit R2 and Cloudflare variable lists plus a "Gitea Secrets" table documenting all 15 required secrets.
+
 ## [1.0.11] - 2026-08-10
 
 ### Added

LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2026 linearvoid.tv (Corey Pellizzi, Georg Sinn)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -5,9 +5,9 @@
 **Repository**: [git.allucanget.biz/zwitschi/linearvoid](https://git.allucanget.biz/zwitschi/linearvoid)
 
 [![Build Status](https://git.allucanget.biz/zwitschi/linearvoid/actions/workflows/ci.yml/badge.svg)](https://git.allucanget.biz/zwitschi/linearvoid/actions)
-[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Gitea](https://img.shields.io/badge/Gitea-1.27.1-blue)](https://git.allucanget.biz)
-[![Version](https://img.shields.io/badge/version-1.0.11-blue)](https://git.allucanget.biz/zwitschi/linearvoid/releases)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.13-blue)](https://git.allucanget.biz/zwitschi/linearvoid/releases)
 [![Release Notes](https://img.shields.io/badge/release-notes-green)](CHANGELOG.md)
 
 ## Architecture
@@ -46,69 +46,177 @@ flowchart TD
     P -->|sync| R2
 ```
 
+A detailed description of the Streaming architecture, playout, and delivery is available in [`docs/STREAMING.md`](docs/STREAMING.md).
+
 ## Project Structure
 
+This structure directly reflects the building blocks, runtime flows, deployment view, and cross-cutting concepts defined in the arc42 documentation.
+
 ```text
 linearvoid/
-├── frontend/                  # Static Single-Page Application (HTML/CSS/JS)
-│   ├── src/
-│   │   ├── components/        # Video player, chat sidebar, now-playing overlay
-│   │   ├── js/                # hls.js integration, WebSocket client, UI logic
-│   │   └── styles/            # Tailwind / custom CSS
-│   ├── index.html
-│   └── package.json           # Build tools (Vite recommended)
-├── backend/
-│   ├── playout/               # Continuous HLS generation from playlist
-│   │   ├── src/               # FFmpeg orchestration, playlist manager
-│   │   ├── config/
-│   │   └── Dockerfile
-│   ├── chat/                  # Real-time WebSocket service
-│   │   ├── src/               # Rooms, DMs, moderation, presence (Node/Go)
-│   │   ├── config/
-│   │   └── Dockerfile
-│   └── shared/                # Common utilities, types, normalization helpers
-├── infrastructure/            # Deployment, IaC, Cloudflare configs
-│   ├── docker-compose.yml     # Local/dev orchestration
-│   ├── nginx/                 # Proxy, static serving, HLS delivery
-│   ├── cloudflare/            # Cache rule examples, Workers
-│   └── terraform/             # (optional) provisioning
-├── scripts/                   # Automation scripts
-│   ├── normalize-video.sh     # Pre-process MP4s (codec, keyframes, CRF)
-│   ├── sync-to-r2.sh          # Upload segments/manifests to R2
-│   └── backup.sh
-├── monitoring/                # Dashboards, alerts, logging
-│   ├── grafana/
-│   └── prometheus/
-├── docs/
-│   └── architecture/
-│       ├── README.md          # arc42 template (fully populated)
-│       └── adr/
-│           ├── ADR-001.md             # Consolidated decision record
-│           ├── ADR-002-module-structure.md
-│           ├── ADR-003-tech-stack.md
-│           ├── ADR-004-admin-video.md
-│           ├── ADR-005-admin-moderation-analytics.md
-│           ├── ADR-006-data-storage.md
-│           └── ADR-007-redis-usage.md
-├── .env.example
-├── .gitignore
-├── docker-compose.yml         # Top-level for dev (playout + chat + nginx)
-├── README.md
-└── LICENSE
+├── docs/                   # see Documentation section below
+├── backend/                # see Backend section below
+├── frontend/               # see Frontend section below
+├── infrastructure/         # see Infrastructure section below
+├── monitoring/             # see Monitoring section below
+├── scripts/                # see Scripts section below
+├── .editorconfig           # EditorConfig for consistent coding styles
+├── .env.example            # Example environment variables for local development
+├── .gitignore              # Ignore node_modules, build artifacts, etc.
+├── .prettierignore         # Ignore files for Prettier formatting
+├── CHANGELOG.md            # Release notes and version history
+├── CONTRIBUTING.md         # Contribution guidelines
+├── docker-compose.prod.yml # Production deployment (Hetzner + Cloudflare)
+├── docker-compose.yml      # Top-level for dev (playout + chat + nginx)
+└── README.md               # This file
 ```
 
-### Folder Explanations
+### Documentation
 
-- **`frontend/`**: The viewer experience — minimal, modern SPA with Tailwind + Alpine.js (or vanilla). Uses `hls.js` for playback and a WebSocket client for chat.
-- **`backend/playout/`**: Core linear engine. FFmpeg consumes a normalized playlist and outputs continuous HLS. Includes normalization validation.
-- **`backend/chat/`**: Independent WebSocket service (Node.js/Socket.io or Go). Handles public rooms, private DMs, presence (Redis), persistence (PostgreSQL/SQLite), rate limiting, and moderation.
-- **`backend/shared/`**: Reusable code (types, utils, video validation).
-- **`infrastructure/`**: Everything needed to deploy and configure the stack (Docker, Nginx, Cloudflare rules, future Terraform).
-- **`scripts/`**: One-off and CI-friendly scripts for video preparation, R2 sync, backups, and playlist management.
-- **`monitoring/`**: Grafana dashboards, Prometheus rules, logging configuration.
-- **`docs/architecture/`**: Complete arc42 documentation + ADRs 001-007 (the single source of truth for all architectural decisions).
+- `docs/`: Folder containing all documentation for the project, including architecture, ADRs, operational procedures, and setup guides.
+- `docs/architecture/`: Architecture documentation, including high-level system architecture, component interactions, and decision records (ADRs).
 
-This structure directly reflects the building blocks, runtime flows, deployment view, and cross-cutting concepts defined in the arc42 documentation.
+see [README.md](docs/README.md) for full architecture, ADRs, and operational documentation.
+
+### Backend
+
+- `backend/playout/`: Core linear engine. FFmpeg consumes a normalized playlist and outputs continuous HLS. Includes normalization validation.
+- `backend/chat/`: Independent WebSocket service (Node.js/Socket.io or Go). Handles public rooms, private DMs, presence (Redis), persistence (PostgreSQL/SQLite), rate limiting, and moderation.
+- `backend/shared/`: Reusable code (types, utils, video validation).
+
+```text
+backend/
+├── chat/                               # WebSocket chat service (Node.js or Go)
+│   ├── src/                            # Chat service source code (rooms, DMs, moderation)
+|   |   ├── auth/                       # Admin authentication and session management
+|   |   |   ├── auth_test.go            # Unit tests for authentication
+|   |   |   └── auth.go                 # Authentication logic (login, session validation)
+|   |   ├── config/                     # Configuration files for chat service
+|   |   |   ├── config_test.go          # Unit tests for configuration
+|   |   |   └── config.go               # Configuration loading and validation
+|   |   ├── db/                         # Database access and models
+|   |   |   ├── db_test.go              # Unit tests for database access
+|   |   |   ├── db.go                   # Database connection and query logic
+|   |   |   ├── models.go               # Database models (users, messages, rooms)
+|   |   |   └── redis.go                # Redis connection and presence management
+|   |   ├── handlers/                   # WebSocket message handlers
+|   |   |   ├── handlers_test.go        # Unit tests for WebSocket message handlers
+|   |   |   └── handlers.go             # WebSocket message handling logic
+|   |   ├── media/                      # Media-related utilities (e.g., video validation)
+|   |   |   ├── media_test.go           # Unit tests for media-related utilities
+|   |   |   └── media.go                # Media-related utility functions
+|   |   ├── metrics/                    # Prometheus metrics endpoints
+|   |   |   ├── metrics_test.go         # Unit tests for Prometheus metrics
+|   |   |   └── metrics.go              # Prometheus metrics collection and exposition
+|   |   ├── ratelimit/                  # Rate limiting logic (Redis-based)
+|   |   |   ├── ratelimit_test.go       # Unit tests for rate limiting
+|   |   |   └── ratelimit.go            # Rate limiting logic using Redis
+|   |   ├── ws/                         # WebSocket handlers
+|   |   |   ├── ws_test.go              # Unit tests for WebSocket handlers
+|   |   |   └── ws.go                   # WebSocket connection and message handling
+|   |   └── main.go                     # Entry point for chat service
+|   ├── Dockerfile                      # Dockerfile for chat service
+|   ├── go.mod                          # Go module file for chat service
+|   └── go.sum                          # Go checksum file for chat service
+└── playout/                            # Continuous HLS generation from playlist (Go)
+    ├── demodata/                       # Sample media and playlist files for testing
+    |   ├── media/                      # Sample media files for testing
+    |   └── playlist/                   # Sample playlist files for testing
+    ├── src/                            # Playout service source code (FFmpeg orchestration)
+    |   ├── go.mod                      # Go module file for playout service
+    |   ├── go.sum                      # Go checksum file for playout service
+    |   ├── playlist_test.go            # Unit tests for playlist management
+    |   └── playlist.go                 # Playlist management logic
+    └── testdata/                       # Test data for playout service (sample playlists, media)
+    |   ├── comments_only.txt           # Sample playlist with comments only
+    |   ├── empty_playlist.txt          # Sample empty playlist
+    |   ├── invalid_24fps.mp4           # Sample invalid 24fps video for testing
+    |   ├── invalid_h265.mp4            # Sample invalid H.265 video for testing
+    |   ├── mixed_valid_invalid.txt     # Sample playlist with mixed valid and invalid entries
+    |   ├── valid_720p30.mp4            # Sample valid 720p30 video for testing
+    |   └── valid_playlist.txt          # Sample valid playlist for testing
+    ├── Dockerfile                      # Dockerfile for the playout service
+    └── start-playout.sh                # Script to start the playout service
+```
+
+### Frontend
+
+The viewer experience — minimal, modern SPA with custom CSS + vanilla JS. Uses `hls.js` for playback and a WebSocket client for chat.
+
+```text
+frontend/
+├── admin/                  # Admin SPA (playlist management, moderation, analytics)
+│   ├── login/              # Login page for admin authentication
+|   |  └── index.html       # Admin login page
+|   └── index.html          # Admin SPA
+├── public/                 # Static assets (favicon, images, etc.)
+│   ├── admin/              # Admin static assets
+|   |  ├── analytics.html   # Analytics dashboard page
+|   |  ├── chat-log.html    # Chat log viewer page
+|   |  ├── dashboard.html   # Admin dashboard page
+|   |  ├── moderation.html  # User moderation page
+|   |  ├── playlist.html    # Playlist management page
+|   |  ├── schedule.html    # Schedule overrides page
+|   |  ├── system.html      # System configuration page
+|   |  ├── upload.html      # Video upload page
+|   |  └── users.html       # User management page
+│   ├── favicon.ico         # Favicon for the SPA
+|   └── icons.svg           # SVG icons for the SPA
+├── src/                    # Source code for the SPA
+│   ├── assets/             # Images, fonts, and other static assets
+|   |  ├── hero.png         # Hero image for the SPA
+|   |  ├── typescript.svg   # TypeScript logo for the SPA
+|   |  └── vite.svg         # Vite logo for the SPA
+│   ├── admin.test.ts       # Admin frontend tests (Vitest)
+│   ├── admin.ts            # Admin SPA logic (playlist, moderation, analytics)
+│   ├── counter.ts          # Counter component for testing
+│   ├── main.test.ts        # Main frontend tests (Vitest)
+│   ├── main.ts             # Main SPA logic (hls.js player, WebSocket chat)
+│   └── style.css           # Custom CSS for the SPA
+├── .gitignore              # Ignore node_modules, build artifacts, etc.
+├── index.html              # Main SPA entry point
+├── package-lock.json       # Lockfile for npm dependencies
+├── package.json            # Build tools (Vite recommended)
+├── tsconfig.json           # TypeScript configuration
+├── vite.config.ts          # Vite configuration
+└── vitest.config.ts        # Vitest configuration
+```
+
+### Infrastructure
+
+Everything needed to deploy and configure the stack (Docker, Nginx, Cloudflare rules, future Terraform).
+
+- Cloudflare
+  - [worker.js](infrastructure/cloudflare/worker.js) — Cloudflare Worker serving the static SPA and adding immutable cache headers to HLS segments
+- Nginx
+  - [Dockerfile](infrastructure/nginx/Dockerfile) — builds Nginx with custom config
+  - [nginx.conf](infrastructure/nginx/nginx.conf) — reverse proxy, static SPA, HLS delivery
+
+### Monitoring
+
+Grafana dashboards, Prometheus rules, logging configuration.
+
+- Grafana
+  - dashboards
+    - [dashboard.json](monitoring//grafana/dashboards/dashboard.json) — operational dashboards for playout, chat, and Redis
+    - [dashboard.yml](monitoring//grafana/dashboards/dashboard.yml) — operational dashboards for playout, chat, and Redis
+  - datasources
+    - [datasource.yml](monitoring/grafana/datasources/datasource.yml) — Prometheus datasource configuration
+  - [dashboard.json](monitoring/grafana/dashboard.json) — operational dashboards for playout, chat, and Redis
+- Prometheus
+  - [alerts.yml](monitoring/prometheus/alerts.yml) — alerting rules for playout, chat, Redis, and system health
+  - [prometheus.yml](monitoring/prometheus/prometheus.yml) — scrape targets for playout, chat, Redis, and system metrics
+
+### Scripts
+
+One-off and CI-friendly scripts for video preparation, R2 sync, backups, and playlist management.
+
+- loadtest/
+  - [admin-api.js](scripts/loadtest/admin-api.js) — admin API load test script
+  - [run-loadtests.ps1](scripts/loadtest/run-loadtests.ps1) — PowerShell script to run load tests
+  - [summarize-artillery.ps1](scripts/loadtest/summarize-artillery.ps1) — PowerShell script to summarize Artillery load test results
+  - [summarize-k6.ps1](scripts/loadtest/summarize-k6.ps1) — PowerShell script to summarize k6 load test results
+  - [ws-chat.yml](scripts/loadtest/ws-chat.yml) — WebSocket chat load test configuration
 
 ## Getting Started
 
@@ -154,8 +262,8 @@ See the [architecture docs](docs/architecture/README.md) for detailed architectu
 | `VITE_PUBLIC_HLS_URL`  | `https://media.linearvoid.tv/hls/playlist.m3u8` | HLS playlist URL                 |
 | `ADMIN_USERNAME`       | `admin`                                         | Admin panel username             |
 | `ADMIN_PASSWORD`       | —                                               | Admin panel password             |
-| `HLS_SEGMENT_DURATION` | `6`                                             | HLS segment duration in seconds  |
-| `HLS_WINDOW_SIZE`      | `24`                                            | HLS playlist window size         |
+| `HLS_SEGMENT_DURATION` | `2`                                             | HLS segment duration in seconds  |
+| `HLS_WINDOW_SIZE`      | `12`                                            | HLS playlist window size         |
 
 Full reference: [`.env.example`](.env.example).
 

backend/chat/go.mod

@@ -6,6 +6,7 @@ require (
 	github.com/glebarez/sqlite v1.11.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/redis/go-redis/v9 v9.7.0
+	golang.org/x/crypto v0.37.0
 	gorm.io/driver/postgres v1.5.11
 	gorm.io/gorm v1.25.12
 )
@@ -24,7 +25,6 @@ require (
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/mattn/go-isatty v0.0.17 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
-	golang.org/x/crypto v0.37.0 // indirect
 	golang.org/x/sync v0.13.0 // indirect
 	golang.org/x/sys v0.32.0 // indirect
 	golang.org/x/text v0.24.0 // indirect

backend/chat/src/auth/auth.go

@@ -137,4 +137,52 @@ func RequireAdmin(store *SessionStore, cookieName string) func(http.HandlerFunc)
 			next(w, r)
 		}
 	}
+}
+
+// UserSessionStore maps user session tokens to usernames with expiry.
+type UserSessionStore struct {
+	mu       sync.Mutex
+	sessions map[string]userSession
+}
+
+type userSession struct {
+	Username  string
+	ExpiresAt time.Time
+}
+
+// NewUserSessionStore creates a new user session store.
+func NewUserSessionStore() *UserSessionStore {
+	return &UserSessionStore{sessions: make(map[string]userSession)}
+}
+
+// Add stores a user session token with username and expiry.
+func (s *UserSessionStore) Add(token, username string, expiresAt time.Time) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.sessions[token] = userSession{Username: username, ExpiresAt: expiresAt}
+}
+
+// Username returns the username for a valid, unexpired token.
+func (s *UserSessionStore) Username(token string) (string, bool) {
+	if token == "" {
+		return "", false
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	sess, ok := s.sessions[token]
+	if !ok {
+		return "", false
+	}
+	if time.Now().After(sess.ExpiresAt) {
+		delete(s.sessions, token)
+		return "", false
+	}
+	return sess.Username, true
+}
+
+// Remove deletes a user session token.
+func (s *UserSessionStore) Remove(token string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	delete(s.sessions, token)
 }

backend/chat/src/auth/auth_test.go

@@ -245,4 +245,33 @@ func TestRequireAdmin(t *testing.T) {
 	if w3.Code != http.StatusUnauthorized {
 		t.Errorf("status = %d, want 401", w3.Code)
 	}
+}
+
+func TestUserSessionStore(t *testing.T) {
+	store := NewUserSessionStore()
+
+	if _, ok := store.Username(""); ok {
+		t.Error("Username(\"\") = true, want false")
+	}
+
+	token, _ := GenerateToken()
+	store.Add(token, "alice", time.Now().Add(1*time.Hour))
+
+	username, ok := store.Username(token)
+	if !ok || username != "alice" {
+		t.Errorf("Username() = %q, %v; want alice, true", username, ok)
+	}
+
+	// Expired session
+	expired, _ := GenerateToken()
+	store.Add(expired, "bob", time.Now().Add(-1*time.Hour))
+	if _, ok := store.Username(expired); ok {
+		t.Error("Username(expired) = true, want false")
+	}
+
+	// Remove
+	store.Remove(token)
+	if _, ok := store.Username(token); ok {
+		t.Error("Username after Remove = true, want false")
+	}
 }

backend/chat/src/config/config.go

@@ -16,6 +16,7 @@ const (
 	DefaultRateLimitMax          = 10
 	DefaultRateLimitWindow       = 10 * time.Second
 	DefaultAdminSessionTTL       = 12 * time.Hour
+	DefaultUserSessionTTL        = 30 * 24 * time.Hour
 	DefaultChatPort              = "3000"
 )
 
@@ -68,6 +69,19 @@ func AdminSessionTTL() time.Duration {
 	return time.Duration(hours) * time.Hour
 }
 
+// UserSessionTTL returns the user session TTL from env or default (30 days).
+func UserSessionTTL() time.Duration {
+	raw := strings.TrimSpace(os.Getenv("USER_SESSION_TTL_HOURS"))
+	if raw == "" {
+		return DefaultUserSessionTTL
+	}
+	hours, err := strconv.Atoi(raw)
+	if err != nil || hours <= 0 {
+		return DefaultUserSessionTTL
+	}
+	return time.Duration(hours) * time.Hour
+}
+
 // RateLimitMax returns the chat rate limit max messages per window.
 func RateLimitMax() int {
 	raw := strings.TrimSpace(os.Getenv("CHAT_RATE_LIMIT_MAX"))

backend/chat/src/config/runtime.go

@@ -0,0 +1,221 @@
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+)
+
+// Runtime configuration keys stored in the runtime config file.
+const (
+	keyMatomoURL     = "matomo_url"
+	keyMatomoSiteID  = "matomo_site_id"
+	keyHLSSegmentDur = "hls_segment_duration"
+	keyHLSWindowSize = "hls_window_size"
+)
+
+// Default HLS values used when neither env nor persisted config is set.
+const (
+	defaultHLSSegmentDuration = 2
+	defaultHLSWindowSize      = 12
+)
+
+var (
+	runtimeMu    sync.RWMutex
+	runtimeStore = map[string]string{}
+)
+
+// ConfigPath returns the runtime config JSON file path from env or default.
+// The default lives in the shared playlist volume so the playout service can
+// read the same file (chat has read-write, playout read-only).
+func ConfigPath() string {
+	p := strings.TrimSpace(os.Getenv("CONFIG_PATH"))
+	if p == "" {
+		return "/app/playlist/config.json"
+	}
+	return p
+}
+
+// GetRuntime returns a value from the runtime store and whether it is present.
+func GetRuntime(key string) (string, bool) {
+	runtimeMu.RLock()
+	defer runtimeMu.RUnlock()
+	v, ok := runtimeStore[key]
+	return v, ok
+}
+
+// SetRuntime stores a value in the runtime store (in-memory only).
+func SetRuntime(key, value string) {
+	runtimeMu.Lock()
+	defer runtimeMu.Unlock()
+	runtimeStore[key] = value
+}
+
+// LoadRuntimeConfig loads the persisted runtime config from disk. If the file does
+// not exist, it seeds the store from environment variables.
+func LoadRuntimeConfig() error {
+	data, err := os.ReadFile(ConfigPath())
+	if err != nil {
+		if os.IsNotExist(err) {
+			runtimeMu.Lock()
+			runtimeStore = map[string]string{}
+			runtimeMu.Unlock()
+			seedRuntimeDefaults()
+			return nil
+		}
+		return fmt.Errorf("read runtime config: %w", err)
+	}
+
+	values := map[string]string{}
+	if err := json.Unmarshal(data, &values); err != nil {
+		return fmt.Errorf("parse runtime config: %w", err)
+	}
+
+	runtimeMu.Lock()
+	defer runtimeMu.Unlock()
+	runtimeStore = values
+	return nil
+}
+
+// SaveRuntimeConfig persists the runtime store to disk as JSON.
+func SaveRuntimeConfig() error {
+	runtimeMu.RLock()
+	data, err := json.MarshalIndent(runtimeStore, "", "  ")
+	runtimeMu.RUnlock()
+	if err != nil {
+		return fmt.Errorf("marshal runtime config: %w", err)
+	}
+	if dir := filepath.Dir(ConfigPath()); dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			return fmt.Errorf("create runtime config dir: %w", err)
+		}
+	}
+	if err := os.WriteFile(ConfigPath(), append(data, '\n'), 0o644); err != nil {
+		return fmt.Errorf("write runtime config: %w", err)
+	}
+	return nil
+}
+
+// seedRuntimeDefaults populates the store from environment variables.
+func seedRuntimeDefaults() {
+	if v := strings.TrimSpace(os.Getenv("MATOMO_URL")); v != "" {
+		SetRuntime(keyMatomoURL, v)
+	}
+	if v := strings.TrimSpace(os.Getenv("MATOMO_SITE_ID")); v != "" {
+		SetRuntime(keyMatomoSiteID, v)
+	}
+	if v := strings.TrimSpace(os.Getenv("HLS_SEGMENT_DURATION")); v != "" {
+		SetRuntime(keyHLSSegmentDur, v)
+	}
+	if v := strings.TrimSpace(os.Getenv("HLS_WINDOW_SIZE")); v != "" {
+		SetRuntime(keyHLSWindowSize, v)
+	}
+}
+
+// MatomoURL returns the Matomo analytics URL.
+func MatomoURL() string {
+	if v, ok := GetRuntime(keyMatomoURL); ok && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return strings.TrimSpace(os.Getenv("MATOMO_URL"))
+}
+
+// MatomoSiteID returns the Matomo site ID.
+func MatomoSiteID() string {
+	if v, ok := GetRuntime(keyMatomoSiteID); ok && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return strings.TrimSpace(os.Getenv("MATOMO_SITE_ID"))
+}
+
+// HLSSegmentDuration returns the HLS segment duration in seconds.
+func HLSSegmentDuration() int {
+	raw := ""
+	if v, ok := GetRuntime(keyHLSSegmentDur); ok {
+		raw = strings.TrimSpace(v)
+	}
+	if raw == "" {
+		raw = strings.TrimSpace(os.Getenv("HLS_SEGMENT_DURATION"))
+	}
+	n, err := strconv.Atoi(raw)
+	if err != nil || n <= 0 {
+		return defaultHLSSegmentDuration
+	}
+	return n
+}
+
+// HLSWindowSize returns the HLS playlist window size in segments.
+func HLSWindowSize() int {
+	raw := ""
+	if v, ok := GetRuntime(keyHLSWindowSize); ok {
+		raw = strings.TrimSpace(v)
+	}
+	if raw == "" {
+		raw = strings.TrimSpace(os.Getenv("HLS_WINDOW_SIZE"))
+	}
+	n, err := strconv.Atoi(raw)
+	if err != nil || n <= 0 {
+		return defaultHLSWindowSize
+	}
+	return n
+}
+
+// SetMatomoURL validates and stores the Matomo URL.
+func SetMatomoURL(raw string) error {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		SetRuntime(keyMatomoURL, "")
+		return nil
+	}
+	u, err := url.Parse(raw)
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+		return fmt.Errorf("matomo URL must be an absolute http(s) URL")
+	}
+	SetRuntime(keyMatomoURL, raw)
+	return nil
+}
+
+// SetMatomoSiteID validates and stores the Matomo site ID.
+func SetMatomoSiteID(raw string) error {
+	raw = strings.TrimSpace(raw)
+	if raw != "" {
+		if _, err := strconv.Atoi(raw); err != nil {
+			return fmt.Errorf("matomo site ID must be numeric")
+		}
+	}
+	SetRuntime(keyMatomoSiteID, raw)
+	return nil
+}
+
+// SetHLSSegmentDuration validates (2–15s) and stores the HLS segment duration.
+func SetHLSSegmentDuration(seconds int) error {
+	if seconds < 2 || seconds > 15 {
+		return fmt.Errorf("HLS segment duration must be between 2 and 15 seconds")
+	}
+	SetRuntime(keyHLSSegmentDur, strconv.Itoa(seconds))
+	return nil
+}
+
+// SetHLSWindowSize validates (3–100) and stores the HLS window size.
+func SetHLSWindowSize(size int) error {
+	if size < 3 || size > 100 {
+		return fmt.Errorf("HLS window size must be between 3 and 100 segments")
+	}
+	SetRuntime(keyHLSWindowSize, strconv.Itoa(size))
+	return nil
+}
+
+// RuntimeConfigSnapshot returns the resolved runtime configuration values.
+func RuntimeConfigSnapshot() map[string]any {
+	return map[string]any{
+		"matomoUrl":          MatomoURL(),
+		"matomoSiteId":       MatomoSiteID(),
+		"hlsSegmentDuration": HLSSegmentDuration(),
+		"hlsWindowSize":      HLSWindowSize(),
+	}
+}

backend/chat/src/config/runtime_test.go

@@ -0,0 +1,181 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func resetRuntime(t *testing.T) {
+	t.Helper()
+	runtimeMu.Lock()
+	runtimeStore = map[string]string{}
+	runtimeMu.Unlock()
+	os.Unsetenv("CONFIG_PATH")
+	os.Unsetenv("MATOMO_URL")
+	os.Unsetenv("MATOMO_SITE_ID")
+	os.Unsetenv("HLS_SEGMENT_DURATION")
+	os.Unsetenv("HLS_WINDOW_SIZE")
+}
+
+func TestConfigPath(t *testing.T) {
+	resetRuntime(t)
+	if got := ConfigPath(); got != "/app/playlist/config.json" {
+		t.Errorf("ConfigPath() = %q, want default /app/playlist/config.json", got)
+	}
+
+	os.Setenv("CONFIG_PATH", "/tmp/custom.json")
+	defer os.Unsetenv("CONFIG_PATH")
+	if got := ConfigPath(); got != "/tmp/custom.json" {
+		t.Errorf("ConfigPath() = %q, want /tmp/custom.json", got)
+	}
+}
+
+func TestGetSetRuntime(t *testing.T) {
+	resetRuntime(t)
+	if _, ok := GetRuntime("foo"); ok {
+		t.Errorf("expected missing key")
+	}
+	SetRuntime("foo", "bar")
+	v, ok := GetRuntime("foo")
+	if !ok || v != "bar" {
+		t.Errorf("GetRuntime() = %q, %v; want bar, true", v, ok)
+	}
+}
+
+func TestGettersDefaults(t *testing.T) {
+	resetRuntime(t)
+	if got := MatomoURL(); got != "" {
+		t.Errorf("MatomoURL() = %q, want empty", got)
+	}
+	if got := MatomoSiteID(); got != "" {
+		t.Errorf("MatomoSiteID() = %q, want empty", got)
+	}
+	if got := HLSSegmentDuration(); got != 2 {
+		t.Errorf("HLSSegmentDuration() = %d, want 2", got)
+	}
+	if got := HLSWindowSize(); got != 12 {
+		t.Errorf("HLSWindowSize() = %d, want 12", got)
+	}
+}
+
+func TestGettersEnvFallback(t *testing.T) {
+	resetRuntime(t)
+	os.Setenv("HLS_SEGMENT_DURATION", "4")
+	os.Setenv("HLS_WINDOW_SIZE", "30")
+	os.Setenv("MATOMO_URL", "https://analytics.example.com")
+	os.Setenv("MATOMO_SITE_ID", "7")
+
+	if got := HLSSegmentDuration(); got != 4 {
+		t.Errorf("HLSSegmentDuration() = %d, want 4", got)
+	}
+	if got := HLSWindowSize(); got != 30 {
+		t.Errorf("HLSWindowSize() = %d, want 30", got)
+	}
+	if got := MatomoURL(); got != "https://analytics.example.com" {
+		t.Errorf("MatomoURL() = %q", got)
+	}
+	if got := MatomoSiteID(); got != "7" {
+		t.Errorf("MatomoSiteID() = %q", got)
+	}
+}
+
+func TestLoadRuntimeConfigSeedsFromEnv(t *testing.T) {
+	resetRuntime(t)
+	dir := t.TempDir()
+	os.Setenv("CONFIG_PATH", filepath.Join(dir, "config.json"))
+	os.Setenv("HLS_SEGMENT_DURATION", "8")
+
+	if err := LoadRuntimeConfig(); err != nil {
+		t.Fatalf("LoadRuntimeConfig error: %v", err)
+	}
+	if got := HLSSegmentDuration(); got != 8 {
+		t.Errorf("HLSSegmentDuration() = %d, want 8 (seeded from env)", got)
+	}
+}
+
+func TestSaveAndLoadRuntimeConfig(t *testing.T) {
+	resetRuntime(t)
+	dir := t.TempDir()
+	os.Setenv("CONFIG_PATH", filepath.Join(dir, "config.json"))
+
+	if err := SetHLSSegmentDuration(5); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetHLSWindowSize(30); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetMatomoURL("https://stats.example.com"); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetMatomoSiteID("42"); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := SaveRuntimeConfig(); err != nil {
+		t.Fatalf("SaveRuntimeConfig error: %v", err)
+	}
+
+	// Reset the store and reload from disk.
+	runtimeMu.Lock()
+	runtimeStore = map[string]string{}
+	runtimeMu.Unlock()
+
+	if err := LoadRuntimeConfig(); err != nil {
+		t.Fatalf("LoadRuntimeConfig error: %v", err)
+	}
+
+	if got := HLSSegmentDuration(); got != 5 {
+		t.Errorf("HLSSegmentDuration() = %d, want 5", got)
+	}
+	if got := HLSWindowSize(); got != 30 {
+		t.Errorf("HLSWindowSize() = %d, want 30", got)
+	}
+	if got := MatomoURL(); got != "https://stats.example.com" {
+		t.Errorf("MatomoURL() = %q", got)
+	}
+	if got := MatomoSiteID(); got != "42" {
+		t.Errorf("MatomoSiteID() = %q", got)
+	}
+}
+
+func TestSettersValidation(t *testing.T) {
+	resetRuntime(t)
+
+	if err := SetHLSSegmentDuration(1); err == nil {
+		t.Error("expected error for duration 1")
+	}
+	if err := SetHLSSegmentDuration(20); err == nil {
+		t.Error("expected error for duration 20")
+	}
+	if err := SetHLSSegmentDuration(6); err != nil {
+		t.Errorf("unexpected error for duration 6: %v", err)
+	}
+
+	if err := SetHLSWindowSize(2); err == nil {
+		t.Error("expected error for window 2")
+	}
+	if err := SetHLSWindowSize(101); err == nil {
+		t.Error("expected error for window 101")
+	}
+	if err := SetHLSWindowSize(24); err != nil {
+		t.Errorf("unexpected error for window 24: %v", err)
+	}
+
+	if err := SetMatomoURL("not-a-url"); err == nil {
+		t.Error("expected error for invalid URL")
+	}
+	if err := SetMatomoURL("ftp://example.com"); err == nil {
+		t.Error("expected error for non-http URL")
+	}
+	if err := SetMatomoURL("https://stats.example.com"); err != nil {
+		t.Errorf("unexpected error for valid URL: %v", err)
+	}
+
+	if err := SetMatomoSiteID("abc"); err == nil {
+		t.Error("expected error for non-numeric site ID")
+	}
+	if err := SetMatomoSiteID("99"); err != nil {
+		t.Errorf("unexpected error for numeric site ID: %v", err)
+	}
+}

backend/chat/src/db/db.go

@@ -45,7 +45,7 @@ func InitDB(databaseURL string) (*DBClient, string, error) {
 		return nil, driver, err
 	}
 
-	gormDB.AutoMigrate(&Message{}, &ModerationLog{}, &Media{}, &ScheduleOverride{})
+	gormDB.AutoMigrate(&Message{}, &ModerationLog{}, &Media{}, &ScheduleOverride{}, &User{})
 	log.Printf("%s database initialized (chat history, moderation log, media metadata)", strings.Title(driver))
 
 	return &DBClient{DB: gormDB}, driver, nil

backend/chat/src/db/models.go

@@ -39,6 +39,14 @@ type Media struct {
 	UpdatedAt       time.Time `gorm:"autoUpdateTime" json:"updatedAt"`
 }
 
+// User represents a registered chat user account (ADR-006).
+type User struct {
+	ID           uint      `gorm:"primarykey" json:"id"`
+	Username     string    `gorm:"uniqueIndex;size:32" json:"username"`
+	PasswordHash string    `json:"-"`
+	CreatedAt    time.Time `gorm:"autoCreateTime" json:"createdAt"`
+}
+
 // ScheduleOverride represents a scheduled playlist override (ADR-004)
 type ScheduleOverride struct {
 	ID        uint      `gorm:"primarykey" json:"id"`

backend/chat/src/handlers/handlers.go

@@ -13,6 +13,7 @@ import (
 	"strings"
 	"time"
 
+	"golang.org/x/crypto/bcrypt"
 	"gorm.io/gorm"
 
 	"chat/src/auth"
@@ -197,6 +198,7 @@ type Dependencies struct {
 	Redis       db.RedisClient
 	Hub         *ws.Hub
 	SessionStore *auth.SessionStore
+	UserSessions *auth.UserSessionStore
 	DBDriver    string
 }
 
@@ -333,6 +335,251 @@ func HandleAdminSession(deps *Dependencies) http.HandlerFunc {
 	}
 }
 
+// userSessionCookieName is the cookie for registered chat users.
+const userSessionCookieName = "linearvoid_user_session"
+
+// UserCredentialsPayload is used by registration and login.
+type UserCredentialsPayload struct {
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+// validateUsername checks the username length constraints.
+func validateUsername(username string) error {
+	if len(username) < 3 || len(username) > 32 {
+		return fmt.Errorf("username must be 3-32 characters")
+	}
+	return nil
+}
+
+// validatePassword checks the password length constraints.
+func validatePassword(password string) error {
+	if len(password) < 6 {
+		return fmt.Errorf("password must be at least 6 characters")
+	}
+	return nil
+}
+
+// startUserSession issues a user session cookie for the given username.
+func startUserSession(deps *Dependencies, w http.ResponseWriter, r *http.Request, username string) {
+	token, err := auth.GenerateToken()
+	if err != nil {
+		return
+	}
+	expiresAt := time.Now().Add(config.UserSessionTTL())
+	deps.UserSessions.Add(token, username, expiresAt)
+	auth.SetCookie(w, r, userSessionCookieName, token, expiresAt)
+}
+
+// HandleUserRegister creates a new chat user and signs them in.
+func HandleUserRegister(deps *Dependencies) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		var payload UserCredentialsPayload
+		if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+			http.Error(w, "invalid body", http.StatusBadRequest)
+			return
+		}
+		username := strings.TrimSpace(payload.Username)
+		if err := validateUsername(username); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		if err := validatePassword(payload.Password); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+
+		var count int64
+		deps.DB.Model(&db.User{}).Where("username = ?", username).Count(&count)
+		if count > 0 {
+			http.Error(w, "username already taken", http.StatusConflict)
+			return
+		}
+
+		hash, err := bcrypt.GenerateFromPassword([]byte(payload.Password), bcrypt.DefaultCost)
+		if err != nil {
+			http.Error(w, "failed to hash password", http.StatusInternalServerError)
+			return
+		}
+		user := db.User{Username: username, PasswordHash: string(hash)}
+		if err := deps.DB.Create(&user).Error; err != nil {
+			http.Error(w, "failed to create user", http.StatusInternalServerError)
+			return
+		}
+
+		startUserSession(deps, w, r, user.Username)
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{"username": user.Username})
+	}
+}
+
+// HandleUserLogin verifies credentials and signs the user in.
+func HandleUserLogin(deps *Dependencies) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		var payload UserCredentialsPayload
+		if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+			http.Error(w, "invalid body", http.StatusBadRequest)
+			return
+		}
+		username := strings.TrimSpace(payload.Username)
+
+		var user db.User
+		if err := deps.DB.Where("username = ?", username).First(&user).Error; err != nil {
+			http.Error(w, "invalid credentials", http.StatusUnauthorized)
+			return
+		}
+		if err := bcrypt.CompareHashAndPassword([]byte(user.PasswordHash), []byte(payload.Password)); err != nil {
+			http.Error(w, "invalid credentials", http.StatusUnauthorized)
+			return
+		}
+
+		startUserSession(deps, w, r, user.Username)
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{"username": user.Username})
+	}
+}
+
+// HandleUserSession returns the current user session state.
+func HandleUserSession(deps *Dependencies) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		token, _ := auth.GetTokenFromCookie(r, userSessionCookieName)
+		username, ok := deps.UserSessions.Username(token)
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"authenticated": ok,
+			"username":      username,
+		})
+	}
+}
+
+// HandleUserLogout clears the user session.
+func HandleUserLogout(deps *Dependencies) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		if token, ok := auth.GetTokenFromCookie(r, userSessionCookieName); ok {
+			deps.UserSessions.Remove(token)
+		}
+		auth.ClearCookie(w, r, userSessionCookieName)
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+	}
+}
+
+// currentUsername returns the authenticated username from the user session cookie.
+func currentUsername(deps *Dependencies, r *http.Request) (string, bool) {
+	token, ok := auth.GetTokenFromCookie(r, userSessionCookieName)
+	if !ok {
+		return "", false
+	}
+	return deps.UserSessions.Username(token)
+}
+
+// dmRoomFor returns the canonical DM room for two users (sorted, prefixed).
+func dmRoomFor(a, b string) string {
+	if a > b {
+		a, b = b, a
+	}
+	return "dm:" + a + "-" + b
+}
+
+// HandleUserDMHistory returns paginated private message history with a target user.
+func HandleUserDMHistory(deps *Dependencies) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		username, ok := currentUsername(deps, r)
+		if !ok {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		target := strings.TrimSpace(r.URL.Query().Get("with"))
+		if target == "" {
+			http.Error(w, "missing target user", http.StatusBadRequest)
+			return
+		}
+		limit := 50
+		if raw := r.URL.Query().Get("limit"); raw != "" {
+			if n, err := strconv.Atoi(raw); err == nil && n > 0 && n <= 200 {
+				limit = n
+			}
+		}
+		room := dmRoomFor(username, target)
+
+		query := deps.DB.Where("room = ?", room)
+		if beforeRaw := r.URL.Query().Get("before"); beforeRaw != "" {
+			if t, err := time.Parse(time.RFC3339, beforeRaw); err == nil {
+				query = query.Where("timestamp < ?", t)
+			}
+		}
+		var messages []db.Message
+		if err := query.Order("timestamp desc").Limit(limit).Find(&messages).Error; err != nil {
+			http.Error(w, "failed to load history", http.StatusInternalServerError)
+			return
+		}
+		for i, j := 0, len(messages)-1; i < j; i, j = i+1, j-1 {
+			messages[i], messages[j] = messages[j], messages[i]
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(messages)
+	}
+}
+
+// HandleUserDMSearch searches private messages with a target user.
+func HandleUserDMSearch(deps *Dependencies) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		username, ok := currentUsername(deps, r)
+		if !ok {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		target := strings.TrimSpace(r.URL.Query().Get("with"))
+		q := strings.TrimSpace(r.URL.Query().Get("q"))
+		if target == "" || q == "" {
+			http.Error(w, "missing target or query", http.StatusBadRequest)
+			return
+		}
+		limit := 50
+		if raw := r.URL.Query().Get("limit"); raw != "" {
+			if n, err := strconv.Atoi(raw); err == nil && n > 0 && n <= 200 {
+				limit = n
+			}
+		}
+		room := dmRoomFor(username, target)
+		var messages []db.Message
+		if err := deps.DB.Where("room = ? AND LOWER(text) LIKE ?", room, "%"+strings.ToLower(q)+"%").
+			Order("timestamp desc").Limit(limit).Find(&messages).Error; err != nil {
+			http.Error(w, "failed to search", http.StatusInternalServerError)
+			return
+		}
+		for i, j := 0, len(messages)-1; i < j; i, j = i+1, j-1 {
+			messages[i], messages[j] = messages[j], messages[i]
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(messages)
+	}
+}
+
 // HandleAdminOverview returns the admin dashboard overview.
 func HandleAdminOverview(deps *Dependencies) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
@@ -757,29 +1004,83 @@ func HandleAdminSystemSummary(deps *Dependencies) http.HandlerFunc {
 	}
 }
 
+// HandlePublicMatomo exposes the Matomo analytics settings for the viewer frontend.
+func HandlePublicMatomo() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"matomoUrl":    config.MatomoURL(),
+			"matomoSiteId": config.MatomoSiteID(),
+		})
+	}
+}
+
+// adminConfigResponse builds the admin configuration payload from runtime config
+// and read-only runtime facts.
+func adminConfigResponse(deps *Dependencies) map[string]any {
+	resp := config.RuntimeConfigSnapshot()
+	resp["rateLimitMax"] = config.RateLimitMax()
+	resp["rateLimitWindowSec"] = int(config.RateLimitWindow().Seconds())
+	resp["databaseDriver"] = deps.DBDriver
+	resp["redisEnabled"] = deps.Redis != nil
+	resp["sessionTTLHours"] = int(config.AdminSessionTTL().Hours())
+	return resp
+}
+
 // HandleAdminConfig returns/updates runtime configuration.
 func HandleAdminConfig(deps *Dependencies) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		switch r.Method {
 		case http.MethodGet:
 			w.Header().Set("Content-Type", "application/json")
-			json.NewEncoder(w).Encode(map[string]any{
-				"rateLimitMax":       config.RateLimitMax(),
-				"rateLimitWindowSec": int(config.RateLimitWindow().Seconds()),
-				"databaseDriver":     deps.DBDriver,
-				"redisEnabled":       deps.Redis != nil,
-				"sessionTTLHours":    int(config.AdminSessionTTL().Hours()),
-			})
+			json.NewEncoder(w).Encode(adminConfigResponse(deps))
 		case http.MethodPut:
-			var payload map[string]any
+			// Editable runtime fields (Matomo + HLS). Rate limit fields remain
+			// env-driven and are intentionally read-only here.
+			var payload struct {
+				MatomoURL          *string `json:"matomoUrl"`
+				MatomoSiteID       *string `json:"matomoSiteId"`
+				HLSSegmentDuration *int    `json:"hlsSegmentDuration"`
+				HLSWindowSize      *int    `json:"hlsWindowSize"`
+			}
 			if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
 				http.Error(w, "invalid body", http.StatusBadRequest)
 				return
 			}
-			// Note: rate limit config is read-only at runtime in this refactored version.
-			// To change, restart with env vars.
+			if payload.MatomoURL != nil {
+				if err := config.SetMatomoURL(*payload.MatomoURL); err != nil {
+					http.Error(w, err.Error(), http.StatusBadRequest)
+					return
+				}
+			}
+			if payload.MatomoSiteID != nil {
+				if err := config.SetMatomoSiteID(*payload.MatomoSiteID); err != nil {
+					http.Error(w, err.Error(), http.StatusBadRequest)
+					return
+				}
+			}
+			if payload.HLSSegmentDuration != nil {
+				if err := config.SetHLSSegmentDuration(*payload.HLSSegmentDuration); err != nil {
+					http.Error(w, err.Error(), http.StatusBadRequest)
+					return
+				}
+			}
+			if payload.HLSWindowSize != nil {
+				if err := config.SetHLSWindowSize(*payload.HLSWindowSize); err != nil {
+					http.Error(w, err.Error(), http.StatusBadRequest)
+					return
+				}
+			}
+			if err := config.SaveRuntimeConfig(); err != nil {
+				http.Error(w, fmt.Sprintf("failed to save config: %v", err), http.StatusInternalServerError)
+				return
+			}
 			w.Header().Set("Content-Type", "application/json")
-			json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+			json.NewEncoder(w).Encode(adminConfigResponse(deps))
 		default:
 			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 		}
@@ -976,9 +1277,9 @@ func HandleAdminMedia(deps *Dependencies) http.HandlerFunc {
 			}
 
 			normResult := media.ValidateNormalization(targetPath)
-			status := "ready"
+			status := media.StatusReady
 			if !normResult.Valid {
-				status = "needs_normalization"
+				status = media.StatusNeedsNormalization
 			}
 
 			filename := filepath.Base(targetPath)
@@ -998,6 +1299,10 @@ func HandleAdminMedia(deps *Dependencies) http.HandlerFunc {
 				return
 			}
 
+			if !normResult.Valid {
+				go normalizeMediaRecord(deps, mediaRecord)
+			}
+
 			files, err := media.ListFiles(deps.DB)
 			if err != nil {
 				http.Error(w, fmt.Sprintf("failed to list media files: %v", err), http.StatusInternalServerError)
@@ -1307,9 +1612,9 @@ func HandleAdminMediaUploads(deps *Dependencies) http.HandlerFunc {
 			}
 
 			normResult := media.ValidateNormalization(targetPath)
-			status := "ready"
+			status := media.StatusReady
 			if !normResult.Valid {
-				status = "needs_normalization"
+				status = media.StatusNeedsNormalization
 			}
 
 			filename := filepath.Base(targetPath)
@@ -1329,6 +1634,10 @@ func HandleAdminMediaUploads(deps *Dependencies) http.HandlerFunc {
 				return
 			}
 
+			if !normResult.Valid {
+				go normalizeMediaRecord(deps, mediaRecord)
+			}
+
 			_ = os.RemoveAll(media.UploadSessionDir(mediaDir, uploadID))
 
 			files, err := media.ListFiles(deps.DB)
@@ -1348,6 +1657,11 @@ func HandleAdminMediaUploads(deps *Dependencies) http.HandlerFunc {
 func HandleAdminMediaByID(deps *Dependencies) http.HandlerFunc {
 	mediaDir := config.MediaDir()
 	return func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasSuffix(r.URL.Path, "/normalize") {
+			handleNormalizeMedia(deps, w, r)
+			return
+		}
+
 		mediaID, err := media.GetMediaIDFromPath(r.URL.Path, "/api/admin/media/")
 		if err != nil {
 			http.Error(w, err.Error(), http.StatusBadRequest)
@@ -1424,6 +1738,75 @@ func HandleAdminMediaByID(deps *Dependencies) http.HandlerFunc {
 	}
 }
 
+// normalizeMediaRecord runs ffmpeg normalization for a media record and updates
+// its status, path, duration, and size. Safe to run asynchronously.
+func normalizeMediaRecord(deps *Dependencies, record db.Media) {
+	src := record.Path
+	dst := strings.TrimSuffix(src, filepath.Ext(src)) + ".normalized.mp4"
+
+	if err := deps.DB.Model(&record).Update("status", media.StatusNormalizing).Error; err != nil {
+		return
+	}
+
+	duration, size, err := media.NormalizeVideo(src, dst)
+	if err != nil {
+		_ = deps.DB.Model(&record).Updates(map[string]any{
+			"status": media.StatusNormalizationFailed,
+			"tags":   `"normalization":false`,
+		}).Error
+		return
+	}
+
+	_ = deps.DB.Model(&record).Updates(map[string]any{
+		"path":             dst,
+		"filename":         filepath.Base(dst),
+		"size_bytes":       size,
+		"duration_seconds": duration,
+		"status":           media.StatusReady,
+		"tags":             `"normalization":true`,
+	}).Error
+}
+
+// handleNormalizeMedia handles POST /api/admin/media/{id}/normalize.
+func handleNormalizeMedia(deps *Dependencies, w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	idPart := strings.TrimSuffix(r.URL.Path, "/normalize")
+	idPart = strings.TrimPrefix(idPart, "/api/admin/media/")
+	idPart = strings.Trim(idPart, "/")
+	mediaID, err := strconv.ParseUint(idPart, 10, 64)
+	if err != nil || mediaID == 0 {
+		http.Error(w, "invalid media id", http.StatusBadRequest)
+		return
+	}
+
+	var record db.Media
+	if err := deps.DB.First(&record, mediaID).Error; err != nil {
+		http.Error(w, "media item not found", http.StatusNotFound)
+		return
+	}
+
+	if record.Status == media.StatusNormalizing {
+		http.Error(w, "normalization already in progress", http.StatusConflict)
+		return
+	}
+
+	record.Status = media.StatusNormalizing
+	if err := deps.DB.Model(&record).Update("status", media.StatusNormalizing).Error; err != nil {
+		http.Error(w, fmt.Sprintf("failed to update media status: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	go normalizeMediaRecord(deps, record)
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusAccepted)
+	json.NewEncoder(w).Encode(mediaEntryFromRecord(record))
+}
+
 // HandleAdminChatLog lists chat log entries.
 func HandleAdminChatLog(deps *Dependencies) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
@@ -1446,7 +1829,7 @@ func HandleAdminChatLog(deps *Dependencies) http.HandlerFunc {
 			limit = parsedLimit
 		}
 
-		dbQuery := deps.DB.Model(&db.Message{})
+		dbQuery := deps.DB.Model(&db.Message{}).Where("type <> ?", "system")
 		if room != "" {
 			dbQuery = dbQuery.Where("room = ?", room)
 		}

backend/chat/src/handlers/handlers_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -14,11 +15,13 @@ import (
 	"time"
 
 	"github.com/glebarez/sqlite"
+	"golang.org/x/crypto/bcrypt"
 	"gorm.io/gorm"
 
 	"chat/src/auth"
 	"chat/src/config"
 	"chat/src/db"
+	"chat/src/media"
 	"chat/src/ws"
 )
 
@@ -100,7 +103,14 @@ func setupTestDeps(t *testing.T) (*Dependencies, *gorm.DB, *auth.SessionStore) {
 	if err != nil {
 		t.Fatalf("failed to open test DB: %v", err)
 	}
-	gormDB.AutoMigrate(&db.Message{}, &db.ModerationLog{}, &db.Media{}, &db.ScheduleOverride{})
+	// A single connection keeps the in-memory SQLite database shared across
+	// goroutines (each :memory: connection would otherwise be a separate DB).
+	sqlDB, err := gormDB.DB()
+	if err != nil {
+		t.Fatalf("failed to get sql.DB: %v", err)
+	}
+	sqlDB.SetMaxOpenConns(1)
+	gormDB.AutoMigrate(&db.Message{}, &db.ModerationLog{}, &db.Media{}, &db.ScheduleOverride{}, &db.User{})
 	mr := newMockRedis()
 	sessionStore := auth.NewSessionStore()
 	hub := ws.NewHub(gormDB, mr, "test-instance", 10, 10*time.Second, config.AdminUsername())
@@ -110,6 +120,7 @@ func setupTestDeps(t *testing.T) (*Dependencies, *gorm.DB, *auth.SessionStore) {
 		Redis:        mr,
 		Hub:          hub,
 		SessionStore: sessionStore,
+		UserSessions: auth.NewUserSessionStore(),
 		DBDriver:     "sqlite",
 	}
 	return deps, gormDB, sessionStore
@@ -474,6 +485,7 @@ func TestHandleAdminConfig_Get(t *testing.T) {
 
 func TestHandleAdminConfig_Put(t *testing.T) {
 	deps, _, _ := setupTestDeps(t)
+	setupConfigTest(t)
 
 	handler := HandleAdminConfig(deps)
 	body := `{"rateLimitMax":20}`
@@ -488,6 +500,289 @@ func TestHandleAdminConfig_Put(t *testing.T) {
 	}
 }
 
+// setupConfigTest points the runtime config at a fresh temp file and resets the store.
+func setupConfigTest(t *testing.T) {
+	t.Helper()
+	os.Setenv("CONFIG_PATH", filepath.Join(t.TempDir(), "config.json"))
+	os.Unsetenv("MATOMO_URL")
+	os.Unsetenv("MATOMO_SITE_ID")
+	os.Unsetenv("HLS_SEGMENT_DURATION")
+	os.Unsetenv("HLS_WINDOW_SIZE")
+	if err := config.LoadRuntimeConfig(); err != nil {
+		t.Fatalf("LoadRuntimeConfig: %v", err)
+	}
+	t.Cleanup(func() { os.Unsetenv("CONFIG_PATH") })
+}
+
+func TestHandleAdminConfig_Get_NewFields(t *testing.T) {
+	deps, _, _ := setupTestDeps(t)
+	setupConfigTest(t)
+
+	handler := HandleAdminConfig(deps)
+	req := httptest.NewRequest("GET", "/api/admin/config", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	var cfg map[string]any
+	if err := json.NewDecoder(w.Body).Decode(&cfg); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	for _, k := range []string{"matomoUrl", "matomoSiteId", "hlsSegmentDuration", "hlsWindowSize"} {
+		if _, ok := cfg[k]; !ok {
+			t.Errorf("response missing %q", k)
+		}
+	}
+}
+
+func TestHandleAdminConfig_Put_Persists(t *testing.T) {
+	deps, _, _ := setupTestDeps(t)
+	setupConfigTest(t)
+
+	handler := HandleAdminConfig(deps)
+	body := `{"hlsSegmentDuration":5,"hlsWindowSize":30,"matomoUrl":"https://stats.example.com","matomoSiteId":"42"}`
+	req := httptest.NewRequest("PUT", "/api/admin/config", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	var cfg map[string]any
+	if err := json.NewDecoder(w.Body).Decode(&cfg); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if cfg["hlsSegmentDuration"] != float64(5) {
+		t.Errorf("hlsSegmentDuration = %v, want 5", cfg["hlsSegmentDuration"])
+	}
+	if cfg["hlsWindowSize"] != float64(30) {
+		t.Errorf("hlsWindowSize = %v, want 30", cfg["hlsWindowSize"])
+	}
+	if cfg["matomoUrl"] != "https://stats.example.com" {
+		t.Errorf("matomoUrl = %v", cfg["matomoUrl"])
+	}
+	if cfg["matomoSiteId"] != "42" {
+		t.Errorf("matomoSiteId = %v", cfg["matomoSiteId"])
+	}
+}
+
+func TestHandleAdminConfig_Put_Invalid(t *testing.T) {
+	deps, _, _ := setupTestDeps(t)
+	setupConfigTest(t)
+
+	handler := HandleAdminConfig(deps)
+	body := `{"hlsSegmentDuration":99}`
+	req := httptest.NewRequest("PUT", "/api/admin/config", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("status = %d, want 400", w.Code)
+	}
+}
+
+func TestHandlePublicMatomo(t *testing.T) {
+	setupConfigTest(t)
+
+	handler := HandlePublicMatomo()
+	req := httptest.NewRequest("GET", "/api/matomo", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	var resp map[string]any
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	for _, k := range []string{"matomoUrl", "matomoSiteId"} {
+		if _, ok := resp[k]; !ok {
+			t.Errorf("response missing %q", k)
+		}
+	}
+}
+
+func TestHandleUserRegister_Success(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+
+	handler := HandleUserRegister(deps)
+	body := `{"username":"alice","password":"secret123"}`
+	req := httptest.NewRequest("POST", "/api/auth/register", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (got %s)", w.Code, w.Body.String())
+	}
+	var count int64
+	gormDB.Model(&db.User{}).Where("username = ?", "alice").Count(&count)
+	if count != 1 {
+		t.Errorf("user count = %d, want 1", count)
+	}
+	if len(w.Result().Cookies()) == 0 {
+		t.Error("expected session cookie to be set")
+	}
+}
+
+func TestHandleUserRegister_Duplicate(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+	gormDB.Create(&db.User{Username: "alice", PasswordHash: "x"})
+
+	handler := HandleUserRegister(deps)
+	body := `{"username":"alice","password":"secret123"}`
+	req := httptest.NewRequest("POST", "/api/auth/register", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusConflict {
+		t.Errorf("status = %d, want 409", w.Code)
+	}
+}
+
+func TestHandleUserLogin_Success(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+	hash, _ := bcrypt.GenerateFromPassword([]byte("secret123"), bcrypt.MinCost)
+	gormDB.Create(&db.User{Username: "bob", PasswordHash: string(hash)})
+
+	handler := HandleUserLogin(deps)
+	body := `{"username":"bob","password":"secret123"}`
+	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (got %s)", w.Code, w.Body.String())
+	}
+}
+
+func TestHandleUserLogin_WrongPassword(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+	hash, _ := bcrypt.GenerateFromPassword([]byte("secret123"), bcrypt.MinCost)
+	gormDB.Create(&db.User{Username: "bob", PasswordHash: string(hash)})
+
+	handler := HandleUserLogin(deps)
+	body := `{"username":"bob","password":"wrong"}`
+	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401", w.Code)
+	}
+}
+
+func TestHandleUserSession(t *testing.T) {
+	deps, _, _ := setupTestDeps(t)
+	handler := HandleUserSession(deps)
+
+	// Unauthenticated
+	req := httptest.NewRequest("GET", "/api/auth/session", nil)
+	w := httptest.NewRecorder()
+	handler(w, req)
+	var resp map[string]any
+	json.NewDecoder(w.Body).Decode(&resp)
+	if resp["authenticated"] != false {
+		t.Errorf("authenticated = %v, want false", resp["authenticated"])
+	}
+
+	// Authenticated
+	token, _ := auth.GenerateToken()
+	deps.UserSessions.Add(token, "carol", time.Now().Add(1*time.Hour))
+	req2 := httptest.NewRequest("GET", "/api/auth/session", nil)
+	req2.AddCookie(&http.Cookie{Name: "linearvoid_user_session", Value: token})
+	w2 := httptest.NewRecorder()
+	handler(w2, req2)
+	var resp2 map[string]any
+	json.NewDecoder(w2.Body).Decode(&resp2)
+	if resp2["username"] != "carol" {
+		t.Errorf("username = %v, want carol", resp2["username"])
+	}
+}
+
+func TestHandleUserDMHistory(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+
+	token, _ := auth.GenerateToken()
+	deps.UserSessions.Add(token, "alice", time.Now().Add(1*time.Hour))
+
+	now := time.Now()
+	gormDB.Create(&db.Message{Room: "dm:alice-bob", Username: "alice", Text: "hi bob", Type: "private", Timestamp: now.Add(-2 * time.Hour)})
+	gormDB.Create(&db.Message{Room: "dm:alice-bob", Username: "bob", Text: "hi alice", Type: "private", Timestamp: now.Add(-1 * time.Hour)})
+
+	handler := HandleUserDMHistory(deps)
+	req := httptest.NewRequest("GET", "/api/dm/history?with=bob", nil)
+	req.AddCookie(&http.Cookie{Name: "linearvoid_user_session", Value: token})
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	var msgs []db.Message
+	json.NewDecoder(w.Body).Decode(&msgs)
+	if len(msgs) != 2 {
+		t.Fatalf("len = %d, want 2", len(msgs))
+	}
+	if msgs[0].Text != "hi bob" {
+		t.Errorf("first message = %q, want hi bob (chronological)", msgs[0].Text)
+	}
+}
+
+func TestHandleUserDMHistory_Unauthorized(t *testing.T) {
+	deps, _, _ := setupTestDeps(t)
+
+	handler := HandleUserDMHistory(deps)
+	req := httptest.NewRequest("GET", "/api/dm/history?with=bob", nil)
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401", w.Code)
+	}
+}
+
+func TestHandleUserDMSearch(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+
+	token, _ := auth.GenerateToken()
+	deps.UserSessions.Add(token, "alice", time.Now().Add(1*time.Hour))
+
+	gormDB.Create(&db.Message{Room: "dm:alice-bob", Username: "alice", Text: "meet at 8", Type: "private"})
+	gormDB.Create(&db.Message{Room: "dm:alice-bob", Username: "bob", Text: "see you", Type: "private"})
+
+	handler := HandleUserDMSearch(deps)
+	req := httptest.NewRequest("GET", "/api/dm/search?with=bob&q=meet", nil)
+	req.AddCookie(&http.Cookie{Name: "linearvoid_user_session", Value: token})
+	w := httptest.NewRecorder()
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	var msgs []db.Message
+	json.NewDecoder(w.Body).Decode(&msgs)
+	if len(msgs) != 1 || msgs[0].Text != "meet at 8" {
+		t.Fatalf("search results = %v, want [meet at 8]", msgs)
+	}
+}
+
 func TestHandleAdminRestart(t *testing.T) {
 	deps, _, _ := setupTestDeps(t)
 
@@ -656,6 +951,32 @@ func TestHandleAdminChatLog_FilterByRoom(t *testing.T) {
 	}
 }
 
+func TestHandleAdminChatLog_ExcludesSystem(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+
+	gormDB.Create(&db.Message{Room: "main", Username: "system", Text: "bob joined main", Timestamp: time.Now(), Type: "system"})
+	gormDB.Create(&db.Message{Room: "main", Username: "u1", Text: "hello", Timestamp: time.Now(), Type: "public"})
+
+	handler := HandleAdminChatLog(deps)
+	req := httptest.NewRequest("GET", "/api/admin/chat-log", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("status = %d, want 200", w.Code)
+	}
+
+	var resp ChatLogListResponse
+	json.NewDecoder(w.Body).Decode(&resp)
+	if resp.Total != 1 {
+		t.Errorf("Total = %d, want 1 (system messages must be excluded)", resp.Total)
+	}
+	if len(resp.Entries) != 1 || resp.Entries[0].Text != "hello" {
+		t.Errorf("entries = %v, want only the public chat message", resp.Entries)
+	}
+}
+
 func TestHandleAdminChatLogByID_Get(t *testing.T) {
 	deps, gormDB, _ := setupTestDeps(t)
 
@@ -944,4 +1265,159 @@ func TestHandleAdminMediaUploads_InvalidFile(t *testing.T) {
 	if w.Code != http.StatusBadRequest {
 		t.Errorf("status = %d, want 400", w.Code)
 	}
+}
+
+func TestNormalizeMediaRecord_Success(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+
+	tmpDir := t.TempDir()
+	os.Setenv("MEDIA_DIR", tmpDir)
+	defer os.Unsetenv("MEDIA_DIR")
+
+	srcPath := filepath.Join(tmpDir, "source.mov")
+	if err := os.WriteFile(srcPath, []byte("fake video"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	gormDB.Create(&db.Media{
+		Filename:        "source.mov",
+		OriginalName:    "source.mov",
+		Path:            srcPath,
+		SizeBytes:       10,
+		DurationSeconds: 0,
+		Status:          "needs_normalization",
+		Title:           "source",
+	})
+
+	origNormalize := media.NormalizeVideo
+	t.Cleanup(func() { media.NormalizeVideo = origNormalize })
+	media.NormalizeVideo = func(src, dst string) (int, int64, error) {
+		if err := os.WriteFile(dst, []byte("normalized"), 0o644); err != nil {
+			return 0, 0, err
+		}
+		return 120, 10, nil
+	}
+
+	var record db.Media
+	gormDB.First(&record, 1)
+	normalizeMediaRecord(deps, record)
+
+	var updated db.Media
+	gormDB.First(&updated, 1)
+	if updated.Status != "ready" {
+		t.Errorf("Status = %q, want ready", updated.Status)
+	}
+	if updated.DurationSeconds != 120 {
+		t.Errorf("DurationSeconds = %d, want 120", updated.DurationSeconds)
+	}
+	if !strings.HasSuffix(updated.Path, ".normalized.mp4") {
+		t.Errorf("Path = %q, want .normalized.mp4 suffix", updated.Path)
+	}
+}
+
+func TestNormalizeMediaRecord_Failure(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+
+	tmpDir := t.TempDir()
+	os.Setenv("MEDIA_DIR", tmpDir)
+	defer os.Unsetenv("MEDIA_DIR")
+
+	srcPath := filepath.Join(tmpDir, "source.mov")
+	if err := os.WriteFile(srcPath, []byte("fake video"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	gormDB.Create(&db.Media{
+		Filename:        "source.mov",
+		OriginalName:    "source.mov",
+		Path:            srcPath,
+		SizeBytes:       10,
+		DurationSeconds: 0,
+		Status:          "needs_normalization",
+		Title:           "source",
+	})
+
+	origNormalize := media.NormalizeVideo
+	t.Cleanup(func() { media.NormalizeVideo = origNormalize })
+	media.NormalizeVideo = func(src, dst string) (int, int64, error) {
+		return 0, 0, fmt.Errorf("ffmpeg failed")
+	}
+
+	var record db.Media
+	gormDB.First(&record, 1)
+	normalizeMediaRecord(deps, record)
+
+	var updated db.Media
+	gormDB.First(&updated, 1)
+	if updated.Status != "normalization_failed" {
+		t.Errorf("Status = %q, want normalization_failed", updated.Status)
+	}
+}
+
+func TestHandleAdminMediaByID_Normalize(t *testing.T) {
+	deps, gormDB, _ := setupTestDeps(t)
+
+	tmpDir := t.TempDir()
+	os.Setenv("MEDIA_DIR", tmpDir)
+	defer os.Unsetenv("MEDIA_DIR")
+
+	srcPath := filepath.Join(tmpDir, "source.mov")
+	if err := os.WriteFile(srcPath, []byte("fake video"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	gormDB.Create(&db.Media{
+		Filename:        "source.mov",
+		OriginalName:    "source.mov",
+		Path:            srcPath,
+		SizeBytes:       10,
+		DurationSeconds: 0,
+		Status:          "needs_normalization",
+		Title:           "source",
+	})
+
+	origNormalize := media.NormalizeVideo
+	t.Cleanup(func() { media.NormalizeVideo = origNormalize })
+	media.NormalizeVideo = func(src, dst string) (int, int64, error) {
+		if err := os.WriteFile(dst, []byte("normalized"), 0o644); err != nil {
+			return 0, 0, err
+		}
+		return 90, 9, nil
+	}
+
+	handler := HandleAdminMediaByID(deps)
+	req := httptest.NewRequest("POST", "/api/admin/media/1/normalize", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	if w.Code != http.StatusAccepted {
+		t.Errorf("status = %d, want 202", w.Code)
+	}
+
+	// Wait for the asynchronous normalization goroutine to finish before
+	// t.Cleanup restores media.NormalizeVideo, avoiding a data race on the
+	// package-level mock variable.
+	var updated db.Media
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		gormDB.First(&updated, 1)
+		if updated.Status != media.StatusNormalizing {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("normalization did not complete within 5s")
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	if updated.Status != media.StatusReady {
+		t.Errorf("Status = %q, want ready", updated.Status)
+	}
+	if updated.DurationSeconds != 90 {
+		t.Errorf("DurationSeconds = %d, want 90", updated.DurationSeconds)
+	}
+	if !strings.HasSuffix(updated.Path, ".normalized.mp4") {
+		t.Errorf("Path = %q, want .normalized.mp4 suffix", updated.Path)
+	}
 }

backend/chat/src/main.go

@@ -28,6 +28,11 @@ func main() {
 	rateLimitWindow := config.RateLimitWindow()
 	log.Printf("Rate limit: %d messages per %v", rateLimitMax, rateLimitWindow)
 
+	// Load persisted runtime configuration (Matomo + HLS settings)
+	if err := config.LoadRuntimeConfig(); err != nil {
+		log.Printf("Warning: failed to load runtime config: %v", err)
+	}
+
 	// Initialize Redis
 	redisWrapper := db.InitRedis(config.RedisAddress())
 
@@ -39,6 +44,7 @@ func main() {
 
 	// Initialize session store
 	sessionStore := auth.NewSessionStore()
+	userSessions := auth.NewUserSessionStore()
 
 	// Initialize WebSocket hub
 	hub := ws.NewHub(dbClient.DB, redisWrapper, instanceID, rateLimitMax, rateLimitWindow, config.AdminUsername())
@@ -54,6 +60,7 @@ func main() {
 		Redis:        redisWrapper,
 		Hub:          hub,
 		SessionStore: sessionStore,
+		UserSessions: userSessions,
 		DBDriver:     dbDriver,
 	}
 
@@ -62,6 +69,12 @@ func main() {
 
 	// Register routes
 	http.HandleFunc("/ws", hub.HandleConnection)
+	http.HandleFunc("/api/auth/register", metrics.WrapRequestTiming(handlers.HandleUserRegister(deps)))
+	http.HandleFunc("/api/auth/login", metrics.WrapRequestTiming(handlers.HandleUserLogin(deps)))
+	http.HandleFunc("/api/auth/session", metrics.WrapRequestTiming(handlers.HandleUserSession(deps)))
+	http.HandleFunc("/api/auth/logout", metrics.WrapRequestTiming(handlers.HandleUserLogout(deps)))
+	http.HandleFunc("/api/dm/history", metrics.WrapRequestTiming(handlers.HandleUserDMHistory(deps)))
+	http.HandleFunc("/api/dm/search", metrics.WrapRequestTiming(handlers.HandleUserDMSearch(deps)))
 	http.HandleFunc("/api/admin/login", metrics.WrapRequestTiming(handlers.HandleAdminLogin(deps)))
 	http.HandleFunc("/api/admin/logout", metrics.WrapRequestTiming(handlers.HandleAdminLogout(deps)))
 	http.HandleFunc("/api/admin/session", metrics.WrapRequestTiming(handlers.HandleAdminSession(deps)))
@@ -77,6 +90,7 @@ func main() {
 	http.HandleFunc("/api/admin/schedule", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminSchedule(deps))))
 	http.HandleFunc("/api/admin/schedule/overrides", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminScheduleOverrides(deps))))
 	http.HandleFunc("/api/schedule", metrics.WrapRequestTiming(handlers.HandlePublicSchedule(deps)))
+	http.HandleFunc("/api/matomo", metrics.WrapRequestTiming(handlers.HandlePublicMatomo()))
 	http.HandleFunc("/api/admin/media", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminMedia(deps))))
 	http.HandleFunc("/api/admin/media/uploads", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminMediaUploads(deps))))
 	http.HandleFunc("/api/admin/media/uploads/", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminMediaUploads(deps))))

backend/chat/src/media/media.go

@@ -155,6 +155,71 @@ func ProbeDurationSeconds(mediaPath string) (int, error) {
 	return seconds, nil
 }
 
+// Media status values (ADR-006 media library states).
+const (
+	StatusReady               = "ready"
+	StatusNeedsNormalization  = "needs_normalization"
+	StatusNormalizing         = "normalizing"
+	StatusNormalizationFailed = "normalization_failed"
+)
+
+// runCommand executes an external command and returns its combined output on failure.
+// It is a package variable so tests can substitute a stub.
+var runCommand = func(ctx context.Context, name string, args ...string) error {
+	out, err := exec.CommandContext(ctx, name, args...).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("%s failed: %v (%s)", name, err, strings.TrimSpace(string(out)))
+	}
+	return nil
+}
+
+// normalizationArgs builds the ffmpeg arguments for the Linear Void normalization profile.
+func normalizationArgs(srcPath, dstPath string) []string {
+	return []string{
+		"-y",
+		"-i", srcPath,
+		"-map", "0:v:0", "-map", "0:a:0?",
+		"-vf", "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,fps=30,format=yuv420p",
+		"-c:v", "libx264", "-preset", "medium", "-crf", "21",
+		"-pix_fmt", "yuv420p",
+		"-r", "30", "-g", "60", "-keyint_min", "60", "-sc_threshold", "0",
+		"-c:a", "aac", "-b:a", "160k", "-ar", "48000", "-ac", "2",
+		"-avoid_negative_ts", "make_zero", "-max_muxing_queue_size", "1024",
+		"-movflags", "+faststart",
+		dstPath,
+	}
+}
+
+// normalizeVideo transcodes srcPath to the Linear Void normalization profile,
+// re-verifies the output with ffprobe, and returns its duration (seconds) and size (bytes).
+func normalizeVideo(srcPath, dstPath string) (int, int64, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Hour)
+	defer cancel()
+
+	if err := runCommand(ctx, "ffmpeg", normalizationArgs(srcPath, dstPath)...); err != nil {
+		return 0, 0, err
+	}
+
+	if res := ValidateNormalization(dstPath); !res.Valid {
+		return 0, 0, fmt.Errorf("normalized output failed validation: %s", strings.Join(res.Errors, "; "))
+	}
+
+	duration, err := ProbeDurationSeconds(dstPath)
+	if err != nil {
+		return 0, 0, fmt.Errorf("probe duration failed: %w", err)
+	}
+
+	info, err := os.Stat(dstPath)
+	if err != nil {
+		return 0, 0, fmt.Errorf("stat output failed: %w", err)
+	}
+
+	return duration, info.Size(), nil
+}
+
+// NormalizeVideo is the injectable normalization entry point.
+var NormalizeVideo = normalizeVideo
+
 // DetectMime reads the first 512 bytes of a file to detect its MIME type.
 func DetectMime(filePath string) (string, error) {
 	f, err := os.Open(filePath)

backend/chat/src/media/media_test.go

@@ -1,7 +1,10 @@
 package media
 
 import (
+	"context"
+	"fmt"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -201,4 +204,43 @@ func TestUniqueTargetPath(t *testing.T) {
 	if path != expected {
 		t.Errorf("UniqueTargetPath() = %q, want %q", path, expected)
 	}
+}
+
+func TestNormalizationArgs(t *testing.T) {
+	args := normalizationArgs("/in/movie.mov", "/out/movie.normalized.mp4")
+	joined := strings.Join(args, " ")
+	for _, want := range []string{
+		"-map 0:v:0",
+		"-map 0:a:0?",
+		"-c:v libx264",
+		"-r 30",
+		"-g 60",
+		"-keyint_min 60",
+		"-pix_fmt yuv420p",
+		"-c:a aac",
+		"-ar 48000",
+		"-ac 2",
+		"-avoid_negative_ts make_zero",
+		"/out/movie.normalized.mp4",
+	} {
+		if !strings.Contains(joined, want) {
+			t.Errorf("normalization args missing %q: %v", want, args)
+		}
+	}
+}
+
+func TestNormalizeVideo_FFmpegError(t *testing.T) {
+	origRun := runCommand
+	t.Cleanup(func() { runCommand = origRun })
+
+	runCommand = func(ctx context.Context, name string, args ...string) error {
+		if name != "ffmpeg" {
+			t.Errorf("runCommand name = %q, want ffmpeg", name)
+		}
+		return fmt.Errorf("simulated ffmpeg failure")
+	}
+
+	if _, _, err := normalizeVideo("/in/a.mov", "/out/a.normalized.mp4"); err == nil {
+		t.Fatal("expected error when ffmpeg fails")
+	}
 }

backend/chat/src/ws/ws.go

@@ -41,19 +41,25 @@ type Hub struct {
 	RateLimitWindow time.Duration
 	AdminUsername   string
 	DMsSent         int64
+
+	presenceMu          sync.Mutex
+	presenceTimers      map[string]*time.Timer
+	PresenceGracePeriod time.Duration
 }
 
 // NewHub creates a new WebSocket hub.
 func NewHub(gormDB *gorm.DB, redis db.RedisClient, instanceID string, rateMax int, rateWindow time.Duration, adminUser string) *Hub {
 	return &Hub{
-		clients:         make(map[*websocket.Conn]bool),
-		clientMeta:      make(map[*websocket.Conn]ClientInfo),
-		DB:              gormDB,
-		Redis:           redis,
-		InstanceID:      instanceID,
-		RateLimitMax:    rateMax,
-		RateLimitWindow: rateWindow,
-		AdminUsername:   adminUser,
+		clients:            make(map[*websocket.Conn]bool),
+		clientMeta:         make(map[*websocket.Conn]ClientInfo),
+		DB:                 gormDB,
+		Redis:              redis,
+		InstanceID:         instanceID,
+		RateLimitMax:       rateMax,
+		RateLimitWindow:    rateWindow,
+		AdminUsername:      adminUser,
+		presenceTimers:     make(map[string]*time.Timer),
+		PresenceGracePeriod: 5 * time.Second,
 	}
 }
 
@@ -65,12 +71,14 @@ func (h *Hub) ConnectedClients() int {
 }
 
 // Broadcast sends a message to all connected clients and persists to DB.
+// System messages (join/leave announcements, moderation notices) fan out but
+// are not persisted, so the chat-log table only holds real chat messages.
 func (h *Hub) Broadcast(msg db.Message) {
 	h.mu.Lock()
 	defer h.mu.Unlock()
 
-	// Persist to configured SQL backend.
-	if h.DB != nil {
+	// Persist to configured SQL backend (chat messages only).
+	if h.DB != nil && msg.Type != "system" {
 		h.DB.Create(&msg)
 	}
 
@@ -93,13 +101,59 @@ func (h *Hub) Broadcast(msg db.Message) {
 	}
 }
 
+// scheduleLeaveAnnouncement broadcasts a "left" message after a short grace
+// period so quick reconnects don't produce join/leave spam.
+func (h *Hub) scheduleLeaveAnnouncement(room, username string) {
+	key := room + "\x00" + username
+	h.presenceMu.Lock()
+	if h.presenceTimers == nil {
+		h.presenceTimers = make(map[string]*time.Timer)
+	}
+	grace := h.PresenceGracePeriod
+	if grace <= 0 {
+		grace = 5 * time.Second
+	}
+	h.presenceTimers[key] = time.AfterFunc(grace, func() {
+		h.presenceMu.Lock()
+		delete(h.presenceTimers, key)
+		h.presenceMu.Unlock()
+		h.Broadcast(db.Message{Room: room, Username: "system", Text: username + " left " + room, Type: "system", Timestamp: time.Now()})
+	})
+	h.presenceMu.Unlock()
+}
+
+// cancelLeaveAnnouncement cancels a pending "left" announcement for a
+// room+user and reports whether one existed (i.e. a reconnect within grace).
+func (h *Hub) cancelLeaveAnnouncement(room, username string) bool {
+	key := room + "\x00" + username
+	h.presenceMu.Lock()
+	defer h.presenceMu.Unlock()
+	if timer, ok := h.presenceTimers[key]; ok {
+		timer.Stop()
+		delete(h.presenceTimers, key)
+		return true
+	}
+	return false
+}
+
+// BroadcastTyping notifies other users in the room that a user is typing.
+func (h *Hub) BroadcastTyping(username, room string) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	for conn, info := range h.clientMeta {
+		if info.Room == room && info.Username != username {
+			_ = conn.WriteJSON(db.Message{Room: room, Username: username, Text: "", Type: "typing", Timestamp: time.Now()})
+		}
+	}
+}
+
 // PushChatHistory sends the last N messages for a room via WebSocket.
 func (h *Hub) PushChatHistory(conn *websocket.Conn, room string, limit int) {
 	if h.DB == nil || room == "" {
 		return
 	}
 	var messages []db.Message
-	h.DB.Where("room = ?", room).Order("timestamp desc").Limit(limit).Find(&messages)
+	h.DB.Where("room = ? AND type <> ?", room, "system").Order("timestamp desc").Limit(limit).Find(&messages)
 	// Reverse to chronological order
 	for i := len(messages)/2 - 1; i >= 0; i-- {
 		opp := len(messages) - 1 - i
@@ -147,10 +201,14 @@ func (h *Hub) HandleConnection(w http.ResponseWriter, r *http.Request) {
 	h.clientMeta[conn] = ClientInfo{Username: username, Room: room}
 	h.mu.Unlock()
 
-	// Announce presence (ADR-007)
+	// Announce presence (ADR-007). A reconnect within the grace window cancels
+	// the pending "left" announcement and skips a redundant "joined".
+	rejoined := h.cancelLeaveAnnouncement(room, username)
 	if h.Redis != nil && room != "" {
 		_ = h.Redis.Set(context.Background(), fmt.Sprintf("presence:%s:%s", room, username), "online", 60*time.Second)
-		h.Broadcast(db.Message{Room: room, Username: "system", Text: username + " joined " + room, Type: "system", Timestamp: time.Now()})
+		if !rejoined {
+			h.Broadcast(db.Message{Room: room, Username: "system", Text: username + " joined " + room, Type: "system", Timestamp: time.Now()})
+		}
 	}
 
 	// Push chat history on join (last 50 messages)
@@ -185,7 +243,7 @@ func (h *Hub) HandleConnection(w http.ResponseWriter, r *http.Request) {
 		h.mu.Unlock()
 		if h.Redis != nil && room != "" {
 			_ = h.Redis.Del(context.Background(), fmt.Sprintf("presence:%s:%s", room, username))
-			h.Broadcast(db.Message{Room: room, Username: "system", Text: username + " left " + room, Type: "system", Timestamp: time.Now()})
+			h.scheduleLeaveAnnouncement(room, username)
 		}
 		conn.Close()
 	}()
@@ -224,6 +282,12 @@ func (h *Hub) HandleConnection(w http.ResponseWriter, r *http.Request) {
 			continue
 		}
 
+		// Handle typing indicator (ephemeral — not persisted, not rate-limited)
+		if msg.Type == "typing" {
+			h.BroadcastTyping(msg.Username, msg.Room)
+			continue
+		}
+
 		// Handle private DMs
 		if strings.HasPrefix(msg.Room, "dm:") {
 			h.handlePrivateDM(msg)

backend/chat/src/ws/ws_test.go

@@ -113,6 +113,11 @@ func setupTestHub(t *testing.T) (*Hub, *gorm.DB, *mockRedis) {
 	if err != nil {
 		t.Fatalf("failed to open test DB: %v", err)
 	}
+	sqlDB, err := gormDB.DB()
+	if err != nil {
+		t.Fatalf("failed to get sql.DB: %v", err)
+	}
+	sqlDB.SetMaxOpenConns(1)
 	gormDB.AutoMigrate(&db.Message{}, &db.ModerationLog{})
 	mr := newMockRedis()
 	hub := NewHub(gormDB, mr, "test-instance", 10, 10*time.Second, "admin")
@@ -560,4 +565,47 @@ func TestHub_SubscribeRoomMessages(t *testing.T) {
 	})
 	mr.Publish(ctx, "room:main:messages", string(ownPayload))
 	time.Sleep(50 * time.Millisecond)
+}
+
+func TestHub_Broadcast_SystemNotPersisted(t *testing.T) {
+	hub, _, _ := setupTestHub(t)
+
+	hub.Broadcast(db.Message{Room: "main", Username: "system", Text: "bob joined main", Type: "system", Timestamp: time.Now()})
+
+	var count int64
+	hub.DB.Model(&db.Message{}).Where("type = ?", "system").Count(&count)
+	if count != 0 {
+		t.Errorf("system message count = %d, want 0 (system messages must not persist)", count)
+	}
+
+	hub.Broadcast(db.Message{Room: "main", Username: "bob", Text: "hi", Type: "public", Timestamp: time.Now()})
+	hub.DB.Model(&db.Message{}).Where("type = ?", "public").Count(&count)
+	if count != 1 {
+		t.Errorf("public message count = %d, want 1", count)
+	}
+}
+
+func TestHub_ReconnectGracePeriod(t *testing.T) {
+	hub, _, _ := setupTestHub(t)
+	hub.PresenceGracePeriod = 50 * time.Millisecond
+
+	// Disconnect schedules a delayed "left"; reconnect cancels it.
+	hub.scheduleLeaveAnnouncement("main", "bob")
+	if !hub.cancelLeaveAnnouncement("main", "bob") {
+		t.Error("expected a pending leave announcement to be cancelled on reconnect")
+	}
+	if hub.cancelLeaveAnnouncement("main", "bob") {
+		t.Error("expected no pending leave announcement after cancellation")
+	}
+
+	// A fresh disconnect that is never reconnected fires after the grace period
+	// and cleans up its timer.
+	hub.scheduleLeaveAnnouncement("main", "alice")
+	time.Sleep(120 * time.Millisecond)
+	hub.presenceMu.Lock()
+	_, exists := hub.presenceTimers["main\x00alice"]
+	hub.presenceMu.Unlock()
+	if exists {
+		t.Error("expected the leave announcement timer to clean itself up after firing")
+	}
 }

backend/playout/Dockerfile

@@ -6,7 +6,7 @@ COPY src/go.mod src/go.sum ./
 
 # Download dependencies and build
 RUN go mod download
-RUN CGO_ENABLED=0 GOOS=linux go build -o /playlist-manager ./src/playlist.go
+RUN CGO_ENABLED=0 GOOS=linux GOFLAGS=-mod=mod go build -o /playlist-manager ./src/playlist.go
 
 FROM alpine:3.20
 

backend/playout/src/go.mod

@@ -6,6 +6,7 @@ require (
 	github.com/aws/aws-sdk-go-v2 v1.43.4
 	github.com/aws/aws-sdk-go-v2/config v1.32.35
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.107.0
+	github.com/fsnotify/fsnotify v1.8.0
 )
 
 require (
@@ -24,4 +25,5 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.38.4 // indirect
 	github.com/aws/aws-sdk-go-v2/service/sts v1.45.4 // indirect
 	github.com/aws/smithy-go v1.27.6 // indirect
+	golang.org/x/sys v0.13.0 // indirect
 )

backend/playout/src/go.sum

@@ -34,3 +34,7 @@ github.com/aws/aws-sdk-go-v2/service/sts v1.45.4 h1:w/AryDYMjSUANSQ2uoZxJovUsMTw
 github.com/aws/aws-sdk-go-v2/service/sts v1.45.4/go.mod h1:WeBiAa67azG7Su9Vf+ChGDBLiAozJCXzdjXiPBUwtbc=
 github.com/aws/smithy-go v1.27.6 h1:0zjT8jgK3jbrTT7JJ3EE6JsMhX8JTrZ+f1sEndYDXrA=
 github.com/aws/smithy-go v1.27.6/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/fsnotify/fsnotify v1.8.0 h1:dAwr6QBTBZIkG8roQaJjGof0pp0EeF+tNV7YBP3F/8M=
+github.com/fsnotify/fsnotify v1.8.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

backend/playout/src/playlist.go

@@ -3,12 +3,15 @@ package main
 import (
 	"bufio"
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"net/http"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"sort"
 	"strconv"
 	"strings"
 	"time"
@@ -16,6 +19,8 @@ import (
 	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go-v2/config"
 	"github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/aws/aws-sdk-go-v2/service/s3/types"
+	"github.com/fsnotify/fsnotify"
 )
 
 // VideoFile represents a normalized video entry in the playlist
@@ -31,24 +36,82 @@ var (
 	putObject     = func(client *s3.Client, input *s3.PutObjectInput) (*s3.PutObjectOutput, error) {
 		return client.PutObject(context.TODO(), input)
 	}
-	bucket        = os.Getenv("R2_BUCKET_NAME")
-	playoutMode   = "starting" // "live", "slate", "degraded"
-	restartCount  = 0
-	restartWindow = time.Now()
-	slateDir      = "/app/slate"
-	hlsDir        = "/app/hls"
+	listObjects = func(client *s3.Client, input *s3.ListObjectsV2Input) (*s3.ListObjectsV2Output, error) {
+		return client.ListObjectsV2(context.TODO(), input)
+	}
+	deleteObjects = func(client *s3.Client, input *s3.DeleteObjectsInput) (*s3.DeleteObjectsOutput, error) {
+		return client.DeleteObjects(context.TODO(), input)
+	}
+	bucket             = os.Getenv("R2_BUCKET_NAME")
+	playoutMode        = "starting" // "live", "slate", "degraded"
+	restartCount       = 0
+	restartWindow      = time.Now()
+	slateDir           = "/app/slate"
+	hlsDir             = "/app/hls"
+	hlsSegmentDuration = envWithDefault("HLS_SEGMENT_DURATION", "2")
+	hlsWindowSize      = envWithDefault("HLS_WINDOW_SIZE", "12")
+
+	// Unique segment naming (STREAMING.md contract: r-{runID}/seg-{seq}.m4s)
+	runID       string
+	segSequence uint64
+
+	// Health endpoint detail (STREAMING.md contract)
+	activeItem          string
+	playlistRevision    string
+	lastSegmentSeq      uint64
+	lastR2PubTime       time.Time
+	consecutiveFails    int
+	lastFFmpegStartTime time.Time
+	lastFFmpegExitError error
+
+	// R2 retention cleanup counter
+	r2CleanupObjectsTotal int64
+
+	// R2 retention gauges
+	r2RunsRetained  int64
+	r2BytesRetained int64
+
+	// Continuous playout loop metrics
+	loopsTotal      int64
+	lastRunDuration time.Duration
+	lastRunClean    bool
 )
 
 const (
 	maxRestartsPerMinute = 5
 	slateManifestName    = "playlist.m3u8"
 	// Cache-Control header values for R2 uploads.
-	segmentCacheControl = "public, max-age=31536000, immutable"
-	manifestCacheControl = "public, max-age=2"
+	segmentCacheControl  = "public, max-age=31536000, immutable"
+	manifestCacheControl = "public, max-age=1, s-maxage=2, must-revalidate"
+
+	// R2 retention policy.
+	defaultR2KeepRuns          = 2
+	defaultR2MaxRetentionBytes = int64(10 * 1024 * 1024 * 1024) // 10 GiB
 )
 
-// initR2Client initializes the R2 (S3-compatible) client
+// envWithDefault returns the value of the environment variable or the default if not set.
+func envWithDefault(key, defaultVal string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return defaultVal
+}
+
+// isR2Configured returns true when the required R2 environment variables are set.
+func isR2Configured() bool {
+	return os.Getenv("R2_ENDPOINT") != "" &&
+		os.Getenv("R2_ACCESS_KEY_ID") != "" &&
+		os.Getenv("R2_SECRET_ACCESS_KEY") != "" &&
+		os.Getenv("R2_BUCKET_NAME") != ""
+}
+
+// initR2Client initializes the R2 (S3-compatible) client.
+// Returns an error if required environment variables are missing.
 func initR2Client() error {
+	if !isR2Configured() {
+		return fmt.Errorf("R2 not configured: R2_ENDPOINT, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, or R2_BUCKET_NAME is empty")
+	}
+
 	cfg, err := config.LoadDefaultConfig(context.TODO(),
 		config.WithRegion("auto"),
 		config.WithCredentialsProvider(aws.CredentialsProviderFunc(func(ctx context.Context) (aws.Credentials, error) {
@@ -67,6 +130,84 @@ func initR2Client() error {
 	return nil
 }
 
+// initRunID generates a unique run/session ID for globally unique segment naming (STREAMING.md contract).
+func initRunID() {
+	runID = "r-" + time.Now().UTC().Format("20060102T150405Z")
+	segSequence = 0
+}
+
+// watchAndPublishSegments watches the HLS output directory for new .m4s segments
+// and uploads them to R2 in real time with runID-based keys (STREAMING.md contract).
+func watchAndPublishSegments(ctx context.Context, hlsOutputDir string) {
+	watcher, err := fsnotify.NewWatcher()
+	if err != nil {
+		fmt.Println("Warning: fsnotify unavailable, R2 sync falls back to batch:", err)
+		return
+	}
+	defer watcher.Close()
+
+	if err := watcher.Add(hlsOutputDir); err != nil {
+		fmt.Println("Warning: cannot watch HLS dir:", err)
+		return
+	}
+
+	for {
+		select {
+		case event, ok := <-watcher.Events:
+			if !ok {
+				return
+			}
+			if event.Op&fsnotify.Create != 0 && strings.HasSuffix(event.Name, ".m4s") {
+				// Wait for FFmpeg to finish writing the segment
+				time.Sleep(500 * time.Millisecond)
+				segSequence++
+				lastSegmentSeq = segSequence
+				key := "hls/" + runID + "/" + filepath.Base(event.Name)
+				if err := SyncToR2(event.Name, key); err != nil {
+					consecutiveFails++
+					fmt.Printf("Failed to sync segment %s: %v\n", event.Name, err)
+				} else {
+					consecutiveFails = 0
+					lastR2PubTime = time.Now()
+				}
+			}
+		case err, ok := <-watcher.Errors:
+			if !ok {
+				return
+			}
+			fmt.Println("fsnotify error:", err)
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+// publishManifest uploads the manifest atomically: temp key first, then copy to final key (STREAMING.md contract).
+func publishManifest(localManifestPath string) error {
+	if r2Client == nil {
+		if err := initR2Client(); err != nil {
+			return err
+		}
+	}
+
+	// 1. Upload to temp key
+	if err := SyncToR2(localManifestPath, "hls/playlist.m3u8.tmp"); err != nil {
+		return fmt.Errorf("temp manifest upload failed: %w", err)
+	}
+
+	// 2. Atomic copy to final key
+	_, err := r2Client.CopyObject(context.TODO(), &s3.CopyObjectInput{
+		Bucket:     aws.String(bucket),
+		CopySource: aws.String(bucket + "/hls/playlist.m3u8.tmp"),
+		Key:        aws.String("hls/playlist.m3u8"),
+	})
+	if err != nil {
+		return fmt.Errorf("manifest atomic swap failed: %w", err)
+	}
+
+	return nil
+}
+
 // LoadPlaylist reads a playlist file and returns a list of VideoFile entries
 func LoadPlaylist(playlistPath string) ([]VideoFile, error) {
 	file, err := os.Open(playlistPath)
@@ -336,16 +477,37 @@ func SyncToR2(localPath, r2Key string) error {
 	return err
 }
 
-// HealthHandler provides a simple health check endpoint
+// HealthHandler provides a detailed health check endpoint (STREAMING.md contract)
 func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	status := "healthy"
-	if playoutMode == "slate" {
+	if playoutMode == "slate" || playoutMode == "degraded" {
 		status = "degraded"
 	}
-	w.WriteHeader(http.StatusOK)
-	fmt.Fprintf(w, `{"status":"%s","service":"playout","mode":"%s","restarts":%d,"timestamp":"%s"}`,
-		status, playoutMode, restartCount, time.Now().UTC().Format(time.RFC3339))
+	// Unhealthy if manifest has not advanced for >2 segment durations (12s)
+	if hlsDir != "" && time.Since(lastR2PubTime) > 12*time.Second && playoutMode != "starting" {
+		status = "unhealthy"
+	}
+
+	lastExit := ""
+	if lastFFmpegExitError != nil {
+		lastExit = lastFFmpegExitError.Error()
+	}
+	resp := map[string]any{
+		"status":               status,
+		"service":              "playout",
+		"mode":                 playoutMode,
+		"crash_count":          restartCount,
+		"run_id":               runID,
+		"active_item":          activeItem,
+		"playlist_revision":    playlistRevision,
+		"last_segment_seq":     lastSegmentSeq,
+		"last_r2_pub":          lastR2PubTime.UTC().Format(time.RFC3339),
+		"consecutive_failures": consecutiveFails,
+		"last_exit_error":      lastExit,
+		"timestamp":            time.Now().UTC().Format(time.RFC3339),
+	}
+	json.NewEncoder(w).Encode(resp)
 }
 
 // activateSlate copies pre-rendered slate HLS into the live output directory.
@@ -442,33 +604,57 @@ func resetHLSOutput(hlsDir string) error {
 
 func main() {
 	playlistPath := "/app/playlist/playlist.txt"
-	if len(os.Args) > 1 {
-		playlistPath = os.Args[1]
+	validateOnly := false
+	for _, arg := range os.Args[1:] {
+		switch arg {
+		case "-validate":
+			validateOnly = true
+		default:
+			if !strings.HasPrefix(arg, "-") {
+				playlistPath = arg
+			}
+		}
 	}
 
+	if validateOnly {
+		runValidateOnly(playlistPath)
+		return
+	}
+
+	// Load shared HLS runtime config (written by the chat admin) before starting.
+	loadSharedHLSConfig()
+
 	fmt.Println("=== Linear Void Playout Service Starting ===")
 	fmt.Println("Playlist:", playlistPath)
 	fmt.Println("R2 Bucket:", bucket)
 
+	// Initialize run ID for globally unique segment naming (STREAMING.md)
+	initRunID()
+	fmt.Println("Run ID:", runID)
+
 	// Validate playlist before starting (ADR-001 normalization enforcement)
 	if _, err := ValidatePlaylist(playlistPath); err != nil {
 		fmt.Println("ERROR: Playlist validation failed:", err)
 		os.Exit(1)
 	}
 
-	// Initialize R2 client
+	// Initialize R2 client (skip if not configured — local HLS via nginx still works)
 	if err := initR2Client(); err != nil {
-		fmt.Println("Warning: R2 client initialization failed:", err)
-		// Continue without R2 for local testing
+		fmt.Println("R2 sync disabled:", err)
+	}
+
+	// Start R2 segment retention cleanup (hourly + once at startup)
+	if r2Client != nil {
+		go runR2CleanupLoop()
 	}
 
 	// Start HTTP health check server
 	http.HandleFunc("/health", HealthHandler)
 	http.HandleFunc("/metrics", func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
-		fmt.Fprintln(w, "# HELP linearvoid_playout_restarts_total Total FFmpeg restarts.")
-		fmt.Fprintln(w, "# TYPE linearvoid_playout_restarts_total counter")
-		fmt.Fprintf(w, "linearvoid_playout_restarts_total %d\n", restartCount)
+		fmt.Fprintln(w, "# HELP linearvoid_playout_crashes_total Total FFmpeg crashes (not clean completions).")
+		fmt.Fprintln(w, "# TYPE linearvoid_playout_crashes_total counter")
+		fmt.Fprintf(w, "linearvoid_playout_crashes_total %d\n", restartCount)
 		fmt.Fprintln(w, "# HELP linearvoid_playout_mode Current playout mode (0=live, 1=slate, 2=degraded).")
 		fmt.Fprintln(w, "# TYPE linearvoid_playout_mode gauge")
 		modeVal := 0
@@ -478,6 +664,21 @@ func main() {
 			modeVal = 2
 		}
 		fmt.Fprintf(w, "linearvoid_playout_mode %d\n", modeVal)
+		fmt.Fprintln(w, "# HELP linearvoid_playout_r2_cleanup_objects_total Total R2 objects deleted by retention cleanup.")
+		fmt.Fprintln(w, "# TYPE linearvoid_playout_r2_cleanup_objects_total counter")
+		fmt.Fprintf(w, "linearvoid_playout_r2_cleanup_objects_total %d\n", r2CleanupObjectsTotal)
+		fmt.Fprintln(w, "# HELP linearvoid_playout_r2_runs_retained Number of R2 run folders retained by cleanup.")
+		fmt.Fprintln(w, "# TYPE linearvoid_playout_r2_runs_retained gauge")
+		fmt.Fprintf(w, "linearvoid_playout_r2_runs_retained %d\n", r2RunsRetained)
+		fmt.Fprintln(w, "# HELP linearvoid_playout_r2_bytes_retained Total bytes retained in R2 run folders.")
+		fmt.Fprintln(w, "# TYPE linearvoid_playout_r2_bytes_retained gauge")
+		fmt.Fprintf(w, "linearvoid_playout_r2_bytes_retained %d\n", r2BytesRetained)
+		fmt.Fprintln(w, "# HELP linearvoid_playout_loops_total Total clean playlist completions (loops).")
+		fmt.Fprintln(w, "# TYPE linearvoid_playout_loops_total counter")
+		fmt.Fprintf(w, "linearvoid_playout_loops_total %d\n", loopsTotal)
+		fmt.Fprintln(w, "# HELP linearvoid_playout_run_duration_seconds Duration of the last FFmpeg run in seconds.")
+		fmt.Fprintln(w, "# TYPE linearvoid_playout_run_duration_seconds gauge")
+		fmt.Fprintf(w, "linearvoid_playout_run_duration_seconds %f\n", lastRunDuration.Seconds())
 	})
 	go func() {
 		fmt.Println("Health check server listening on :8081/health")
@@ -493,13 +694,60 @@ func main() {
 			fmt.Printf("[%s] Slate active — attempting live playout recovery...\n", time.Now().Format(time.RFC3339))
 		}
 
-		if err := resetHLSOutput(hlsDir); err != nil {
-			fmt.Println("Failed to reset HLS output:", err)
-			time.Sleep(5 * time.Second)
-			continue
+		// New run ID on each restart for unique R2 segment keys (STREAMING.md)
+		initRunID()
+
+		// Remove run folders older than the retention policy (keep the last N runs,
+		// cap total bytes) now that the next run has started. This never touches the
+		// current or previous run folders.
+		if r2Client != nil {
+			if _, err := cleanupOldRuns(context.Background()); err != nil {
+				fmt.Println("R2 cleanup error:", err)
+			}
 		}
 
-		fmt.Printf("[%s] Starting FFmpeg playout with browser-safe H.264/AAC HLS encoding...\n", time.Now().Format(time.RFC3339))
+		// Reset HLS output only when the playlist changed, we are recovering from a
+		// crash/slate, or this is the first run. Otherwise continue the segment
+		// sequence so the loop is seamless for viewers (no gap on clean loops).
+		fingerprint, fpErr := playlistFingerprint(playlistPath)
+		if fpErr != nil {
+			fmt.Println("Warning: cannot fingerprint playlist:", fpErr)
+			fingerprint = ""
+		}
+		playlistChanged := fingerprint != playlistRevision
+		shouldReset := playlistChanged || playoutMode != "live" || !lastRunClean
+
+		windowSize := 24
+		if ws, err := strconv.Atoi(hlsWindowSize); err == nil && ws > 0 {
+			windowSize = ws
+		}
+
+		startNumber := 0
+		if shouldReset {
+			if err := resetHLSOutput(hlsDir); err != nil {
+				fmt.Println("Failed to reset HLS output:", err)
+				time.Sleep(5 * time.Second)
+				continue
+			}
+			playlistRevision = fingerprint
+		} else {
+			if n, err := hlsNextStartNumber(hlsDir, windowSize); err == nil {
+				startNumber = n
+			}
+		}
+
+		// Start filesystem watcher for real-time R2 segment upload (STREAMING.md).
+		// Only active when R2 is configured; otherwise the watcher is skipped.
+		var watchCtx context.Context
+		var watchCancel context.CancelFunc
+		if r2Client != nil {
+			watchCtx, watchCancel = context.WithCancel(context.Background())
+			go watchAndPublishSegments(watchCtx, hlsDir)
+		}
+
+		lastFFmpegStartTime = time.Now()
+		fmt.Printf("[%s] Starting FFmpeg playout (run %s) with browser-safe H.264/AAC HLS encoding...\n",
+			lastFFmpegStartTime.UTC().Format(time.RFC3339), runID)
 
 		cmd := exec.Command("ffmpeg", "-re", "-f", "concat", "-safe", "0", "-i", playlistPath,
 			"-map", "0:v:0", "-map", "0:a:0?",
@@ -509,57 +757,90 @@ func main() {
 			"-r", "30", "-g", "60", "-keyint_min", "60", "-sc_threshold", "0",
 			"-c:a", "aac", "-ar", "48000", "-ac", "2", "-b:a", "128k",
 			"-f", "hls",
-			"-hls_time", "6",
-			"-hls_list_size", "24",
+			"-hls_time", hlsSegmentDuration,
+			"-hls_list_size", hlsWindowSize,
 			"-hls_segment_type", "fmp4",
 			"-hls_fmp4_init_filename", "init.mp4",
-			"-strftime", "1",
 			"-hls_flags", "delete_segments+independent_segments",
-			"-hls_segment_filename", "/app/hls/segment_%Y%m%d_%H%M%S.m4s",
-			"/app/hls/playlist.m3u8")
+			"-hls_segment_filename", filepath.Join(hlsDir, "seg-%06d.m4s"),
+			"-start_number", strconv.Itoa(startNumber),
+			filepath.Join(hlsDir, "playlist.m3u8"))
 
 		runErr := cmd.Run()
+		runDuration := time.Since(lastFFmpegStartTime)
+		lastFFmpegExitError = runErr
+		lastRunDuration = runDuration
+		lastRunClean = runErr == nil
 
-		// Track restart and check for slate escalation
+		if watchCancel != nil {
+			watchCancel() // Stop the filesystem watcher
+		}
+
+		// After FFmpeg exits, sync remaining segments and publish manifest to R2.
+		// Do this before logging/restart logic so R2 is up to date regardless of exit cause.
+		if r2Client != nil {
+			if err := syncLatestToR2(hlsDir); err != nil {
+				fmt.Println("R2 sync warning:", err)
+			}
+
+			// Publish manifest atomically (STREAMING.md safe publication)
+			manifestPath := filepath.Join(hlsDir, "playlist.m3u8")
+			if err := publishManifest(manifestPath); err != nil {
+				fmt.Println("Manifest publish warning:", err)
+			}
+		}
+
+		// Differentiate clean playlist completion from FFmpeg crash.
+		// A nil error means FFmpeg completed the playlist normally — not a crash.
+		if runErr == nil {
+			loopsTotal++
+			fmt.Printf("[%s] Playlist completed normally after %s. Looping...\n",
+				time.Now().UTC().Format(time.RFC3339), runDuration.Round(time.Second))
+			// If we were in slate mode, a successful run means recovery
+			if playoutMode == "slate" {
+				deactivateSlate()
+			}
+			// Minimal delay for clean loop — just enough for watcher goroutine cleanup
+			time.Sleep(500 * time.Millisecond)
+			continue
+		}
+
+		// FFmpeg exited with an error — this is a real crash
 		restartCount++
-		fmt.Printf("[%s] FFmpeg exited (restart #%d in window): %v\n",
-			time.Now().Format(time.RFC3339), restartCount, runErr)
+		fmt.Printf("[%s] FFmpeg CRASHED after %s (crash #%d in window): %v\n",
+			time.Now().UTC().Format(time.RFC3339), runDuration.Round(time.Second), restartCount, runErr)
 
 		if shouldEscalateToSlate() {
-			fmt.Printf("[%s] CRITICAL: %d restarts in 60s — escalating to slate fallback\n",
-				time.Now().Format(time.RFC3339), restartCount)
+			fmt.Printf("[%s] CRITICAL: %d crashes in 60s — escalating to slate fallback\n",
+				time.Now().UTC().Format(time.RFC3339), restartCount)
 			if err := activateSlate(); err != nil {
 				fmt.Printf("[%s] Slate activation failed: %v — will retry\n",
-					time.Now().Format(time.RFC3339), err)
+					time.Now().UTC().Format(time.RFC3339), err)
 			}
 			// Stay in slate mode, retry recovery after delay
 			time.Sleep(30 * time.Second)
 			continue
 		}
 
-		// If we were in slate but FFmpeg ran successfully, we recovered
-		if playoutMode == "slate" {
+		// If we were in slate but FFmpeg ran long enough to be a recovery, deactivate slate
+		if playoutMode == "slate" && runDuration > 30*time.Second {
 			deactivateSlate()
 		}
 
-		// After FFmpeg run, sync latest segments and manifest to R2
-		if err := syncLatestToR2(hlsDir); err != nil {
-			fmt.Println("R2 sync warning:", err)
-		}
-
-		time.Sleep(5 * time.Second)
+		// Backoff delay after crash before retry
+		time.Sleep(2 * time.Second)
 	}
 }
 
-// syncLatestToR2 uploads new segments and the playlist manifest to R2
+// syncLatestToR2 uploads new segments to R2 with runID-based keys
 func syncLatestToR2(hlsDir string) error {
-	files, err := filepath.Glob(filepath.Join(hlsDir, "segment_*.m4s"))
+	files, err := filepath.Glob(filepath.Join(hlsDir, "seg-*.m4s"))
 	if err != nil {
 		return err
 	}
 
 	for _, f := range files {
-		key := "live/" + filepath.Base(f)
+		key := "hls/" + runID + "/" + filepath.Base(f)
 		if err := SyncToR2(f, key); err != nil {
 			fmt.Printf("Failed to sync %s: %v\n", f, err)
 		} else {
@@ -567,16 +848,303 @@ func syncLatestToR2(hlsDir string) error {
 		}
 	}
 
-	// Sync the live playlist manifest (short TTL per ADR-001)
-	manifestPath := filepath.Join(hlsDir, "playlist.m3u8")
-	if err := SyncToR2(manifestPath, "live/playlist.m3u8"); err != nil {
-		return err
-	}
+	// Sync init segment to run-specific R2 key
 	initPath := filepath.Join(hlsDir, "init.mp4")
-	if err := SyncToR2(initPath, "live/init.mp4"); err != nil {
+	if err := SyncToR2(initPath, "hls/"+runID+"/init.mp4"); err != nil {
 		return err
 	}
-	fmt.Println("Synced live playlist.m3u8 to R2")
+	fmt.Println("Synced init.mp4 to R2")
 
 	return nil
+}
+
+// r2KeepRuns returns how many of the most recent run folders to keep in R2.
+func r2KeepRuns() int {
+	n, err := strconv.Atoi(envWithDefault("R2_KEEP_RUNS", "2"))
+	if err != nil || n < 1 {
+		return defaultR2KeepRuns
+	}
+	return n
+}
+
+// r2MaxRetentionBytes returns the maximum total bytes to retain across run folders.
+func r2MaxRetentionBytes() int64 {
+	n, err := strconv.ParseInt(envWithDefault("R2_MAX_RETENTION_BYTES", "10737418240"), 10, 64)
+	if err != nil || n <= 0 {
+		return defaultR2MaxRetentionBytes
+	}
+	return n
+}
+
+// r2RunFromKey extracts the run folder name ("r-...") from an R2 object key.
+func r2RunFromKey(key string) (string, bool) {
+	rest := strings.TrimPrefix(key, "hls/")
+	if rest == key || !strings.HasPrefix(rest, "r-") {
+		return "", false
+	}
+	if idx := strings.IndexByte(rest, '/'); idx > 0 {
+		return rest[:idx], true
+	}
+	return "", false
+}
+
+// runObjects groups the R2 object keys and total size for a single run folder.
+type runObjects struct {
+	keys []string
+	size int64
+}
+
+// deleteR2Keys deletes the given R2 object keys in batches of up to 1000.
+func deleteR2Keys(keys []string) (int, error) {
+	deleted := 0
+	for i := 0; i < len(keys); i += 1000 {
+		end := i + 1000
+		if end > len(keys) {
+			end = len(keys)
+		}
+		batch := keys[i:end]
+		objects := make([]types.ObjectIdentifier, len(batch))
+		for j, key := range batch {
+			objects[j] = types.ObjectIdentifier{Key: aws.String(key)}
+		}
+		if _, err := deleteObjects(r2Client, &s3.DeleteObjectsInput{
+			Bucket: aws.String(bucket),
+			Delete: &types.Delete{Objects: objects, Quiet: aws.Bool(true)},
+		}); err != nil {
+			return deleted, err
+		}
+		for _, key := range batch {
+			fmt.Printf("R2 cleanup: deleted %s\n", key)
+		}
+		deleted += len(batch)
+	}
+	return deleted, nil
+}
+
+// cleanupOldRuns lists run-scoped objects under hls/, keeps the most recent
+// R2_KEEP_RUNS runs, and deletes older runs. It also enforces the
+// R2_MAX_RETENTION_BYTES cap by removing oldest retained runs first, always
+// keeping at least the newest run. The live manifest keys are never deleted.
+func cleanupOldRuns(ctx context.Context) (int, error) {
+	if r2Client == nil {
+		if err := initR2Client(); err != nil {
+			return 0, err
+		}
+	}
+
+	runs := map[string]*runObjects{}
+	var token *string
+	for {
+		output, err := listObjects(r2Client, &s3.ListObjectsV2Input{
+			Bucket:            aws.String(bucket),
+			Prefix:            aws.String("hls/"),
+			ContinuationToken: token,
+		})
+		if err != nil {
+			return 0, err
+		}
+		for _, obj := range output.Contents {
+			key := aws.ToString(obj.Key)
+			if key == "hls/playlist.m3u8" || key == "hls/playlist.m3u8.tmp" {
+				continue
+			}
+			run, ok := r2RunFromKey(key)
+			if !ok {
+				continue
+			}
+			r, exists := runs[run]
+			if !exists {
+				r = &runObjects{}
+				runs[run] = r
+			}
+			r.keys = append(r.keys, key)
+			if obj.Size != nil {
+				r.size += *obj.Size
+			}
+		}
+		if output.IsTruncated == nil || !*output.IsTruncated {
+			break
+		}
+		token = output.NextContinuationToken
+	}
+
+	if len(runs) == 0 {
+		r2RunsRetained = 0
+		r2BytesRetained = 0
+		return 0, nil
+	}
+
+	// Run IDs are ISO timestamps, so lexicographic order equals chronological order.
+	sortedRuns := make([]string, 0, len(runs))
+	for run := range runs {
+		sortedRuns = append(sortedRuns, run)
+	}
+	sort.Strings(sortedRuns) // ascending: oldest -> newest
+
+	deleteRun := map[string]bool{}
+	keepRuns := r2KeepRuns()
+
+	// Mark all but the newest keepRuns runs for deletion.
+	if len(sortedRuns) > keepRuns {
+		for _, run := range sortedRuns[:len(sortedRuns)-keepRuns] {
+			deleteRun[run] = true
+		}
+	}
+
+	// Enforce the total size cap on retained runs (oldest retained first), always
+	// keeping the newest run even if it alone exceeds the cap.
+	maxBytes := r2MaxRetentionBytes()
+	retained := make([]string, 0, keepRuns)
+	var retainedBytes int64
+	for _, run := range sortedRuns {
+		if !deleteRun[run] {
+			retained = append(retained, run)
+			retainedBytes += runs[run].size
+		}
+	}
+	for i := 0; retainedBytes > maxBytes && i < len(retained)-1; i++ {
+		run := retained[i]
+		deleteRun[run] = true
+		retainedBytes -= runs[run].size
+	}
+
+	var toDelete []string
+	for run, del := range deleteRun {
+		if del {
+			toDelete = append(toDelete, runs[run].keys...)
+		}
+	}
+
+	deleted, err := deleteR2Keys(toDelete)
+	if err != nil {
+		return deleted, err
+	}
+
+	keptRuns := int64(0)
+	keptBytes := int64(0)
+	for run, r := range runs {
+		if !deleteRun[run] {
+			keptRuns++
+			keptBytes += r.size
+		}
+	}
+	r2RunsRetained = keptRuns
+	r2BytesRetained = keptBytes
+
+	r2CleanupObjectsTotal += int64(deleted)
+	return deleted, nil
+}
+
+// runR2CleanupLoop runs retention cleanup once at startup, then hourly.
+func runR2CleanupLoop() {
+	if _, err := cleanupOldRuns(context.Background()); err != nil {
+		fmt.Println("R2 cleanup error:", err)
+	}
+	ticker := time.NewTicker(time.Hour)
+	defer ticker.Stop()
+	for range ticker.C {
+		if _, err := cleanupOldRuns(context.Background()); err != nil {
+			fmt.Println("R2 cleanup error:", err)
+		}
+	}
+}
+
+// playlistFingerprint returns a short hash of the playlist file content, used to
+// detect playlist changes between loops.
+func playlistFingerprint(playlistPath string) (string, error) {
+	data, err := os.ReadFile(playlistPath)
+	if err != nil {
+		return "", err
+	}
+	sum := sha256.Sum256(data)
+	return hex.EncodeToString(sum[:]), nil
+}
+
+// hlsNextStartNumber returns the next segment sequence number to use, and prunes
+// stale segments outside the live window so they do not accumulate across loops.
+func hlsNextStartNumber(hlsDir string, windowSize int) (int, error) {
+	files, err := filepath.Glob(filepath.Join(hlsDir, "seg-*.m4s"))
+	if err != nil {
+		return 0, err
+	}
+
+	seqOf := func(f string) int {
+		base := filepath.Base(f)
+		num := strings.TrimSuffix(strings.TrimPrefix(base, "seg-"), ".m4s")
+		n, err := strconv.Atoi(num)
+		if err != nil {
+			return -1
+		}
+		return n
+	}
+
+	maxSeq := -1
+	for _, f := range files {
+		if n := seqOf(f); n > maxSeq {
+			maxSeq = n
+		}
+	}
+	next := maxSeq + 1
+
+	// Keep the live window; delete older segments no longer referenced.
+	threshold := next - windowSize
+	for _, f := range files {
+		if n := seqOf(f); n >= 0 && n < threshold {
+			if err := os.Remove(f); err != nil && !os.IsNotExist(err) {
+				return next, err
+			}
+		}
+	}
+	return next, nil
+}
+
+// runValidateOnly validates the playlist and exits 0 (valid) or 1 (invalid/missing).
+func runValidateOnly(playlistPath string) {
+	videos, err := ValidatePlaylist(playlistPath)
+	if err != nil {
+		fmt.Println("ERROR: Playlist validation failed:", err)
+		os.Exit(1)
+	}
+	valid := true
+	for _, v := range videos {
+		if v.Valid {
+			fmt.Printf("OK: %s (%.1fs)\n", v.Path, v.Duration)
+		} else {
+			valid = false
+			fmt.Printf("INVALID: %s — %s\n", v.Path, v.Validation)
+		}
+	}
+	if !valid {
+		os.Exit(1)
+	}
+	fmt.Println("Playlist valid.")
+}
+
+// loadSharedHLSConfig reads HLS settings from the shared runtime config file
+// (written by the chat admin service) and overrides the env-derived defaults.
+func loadSharedHLSConfig() {
+	path := envWithDefault("PLAYOUT_CONFIG_PATH", "/app/playlist/config.json")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			fmt.Println("Warning: cannot read shared config:", err)
+		}
+		return
+	}
+	var cfg map[string]string
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		fmt.Println("Warning: cannot parse shared config:", err)
+		return
+	}
+	if v := strings.TrimSpace(cfg["hls_segment_duration"]); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			hlsSegmentDuration = strconv.Itoa(n)
+		}
+	}
+	if v := strings.TrimSpace(cfg["hls_window_size"]); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			hlsWindowSize = strconv.Itoa(n)
+		}
+	}
+	fmt.Printf("Shared HLS config: segment=%ss window=%s\n", hlsSegmentDuration, hlsWindowSize)
 }

backend/playout/src/playlist_test.go

@@ -27,6 +27,8 @@ package main
 // See backend/playout/testdata/*.txt.
 
 import (
+	"context"
+	"fmt"
 	"io"
 	"net/http"
 	"net/http/httptest"
@@ -39,6 +41,7 @@ import (
 
 	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/aws/aws-sdk-go-v2/service/s3/types"
 )
 
 func ensureFFProbeInPath(t *testing.T) {
@@ -241,11 +244,15 @@ func TestHealthHandler(t *testing.T) {
 	// Save and restore globals
 	prevMode := playoutMode
 	prevCount := restartCount
+	prevRunID := runID
 	playoutMode = "live"
 	restartCount = 3
+	runID = "r-20260810T120000Z"
+	lastR2PubTime = time.Now()
 	defer func() {
 		playoutMode = prevMode
 		restartCount = prevCount
+		runID = prevRunID
 	}()
 
 	req := httptest.NewRequest("GET", "/health", nil)
@@ -257,21 +264,30 @@ func TestHealthHandler(t *testing.T) {
 	}
 
 	body := w.Body.String()
-	if !strings.Contains(body, `"healthy"`) {
-		t.Errorf("body missing healthy: %s", body)
-	}
-	if !strings.Contains(body, `"playout"`) {
-		t.Errorf("body missing service: %s", body)
-	}
-	if !strings.Contains(body, `"restarts":3`) {
-		t.Errorf("body missing restarts: %s", body)
+	for _, want := range []string{
+		`"status":"healthy"`,
+		`"service":"playout"`,
+		`"mode":"live"`,
+		`"crash_count":3`,
+		`"run_id":"r-20260810T120000Z"`,
+		`"last_segment_seq"`,
+		`"consecutive_failures"`,
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("body missing %q: %s", want, body)
+		}
 	}
 }
 
 func TestHealthHandler_Degraded(t *testing.T) {
 	prevMode := playoutMode
+	prevR2Pub := lastR2PubTime
 	playoutMode = "slate"
-	defer func() { playoutMode = prevMode }()
+	lastR2PubTime = time.Now() // fresh R2 pub = not unhealthy
+	defer func() {
+		playoutMode = prevMode
+		lastR2PubTime = prevR2Pub
+	}()
 
 	req := httptest.NewRequest("GET", "/health", nil)
 	w := httptest.NewRecorder()
@@ -286,6 +302,26 @@ func TestHealthHandler_Degraded(t *testing.T) {
 	}
 }
 
+func TestHealthHandler_Unhealthy(t *testing.T) {
+	prevMode := playoutMode
+	prevR2Pub := lastR2PubTime
+	playoutMode = "live"
+	lastR2PubTime = time.Now().Add(-30 * time.Second) // stale R2 = unhealthy
+	defer func() {
+		playoutMode = prevMode
+		lastR2PubTime = prevR2Pub
+	}()
+
+	req := httptest.NewRequest("GET", "/health", nil)
+	w := httptest.NewRecorder()
+	HealthHandler(w, req)
+
+	body := w.Body.String()
+	if !strings.Contains(body, `"unhealthy"`) {
+		t.Errorf("body missing unhealthy (stale R2 pub should trigger unhealthy): %s", body)
+	}
+}
+
 func TestShouldEscalateToSlate(t *testing.T) {
 	// Save globals
 	prevCount := restartCount
@@ -462,15 +498,15 @@ func TestSyncToR2(t *testing.T) {
 		return &s3.PutObjectOutput{}, nil
 	}
 
-	if err := SyncToR2(localPath, "live/segment.m4s"); err != nil {
+	if err := SyncToR2(localPath, "hls/segment.m4s"); err != nil {
 		t.Fatalf("SyncToR2 error: %v", err)
 	}
 
 	if gotBucket != "linearvoid-media" {
 		t.Fatalf("bucket = %q, want %q", gotBucket, "linearvoid-media")
 	}
-	if gotKey != "live/segment.m4s" {
-		t.Fatalf("key = %q, want %q", gotKey, "live/segment.m4s")
+	if gotKey != "hls/segment.m4s" {
+		t.Fatalf("key = %q, want %q", gotKey, "hls/segment.m4s")
 	}
 	if string(gotBody) != "segment-bytes" {
 		t.Fatalf("body = %q, want %q", string(gotBody), "segment-bytes")
@@ -555,4 +591,309 @@ func TestSyncToR2_NoCacheHeadersForUnknownExt(t *testing.T) {
 	if gotContentType != "" {
 		t.Fatalf("ContentType = %q, want empty", gotContentType)
 	}
+}
+
+func TestR2KeepRuns(t *testing.T) {
+	os.Setenv("R2_KEEP_RUNS", "")
+	if got := r2KeepRuns(); got != 2 {
+		t.Errorf("default = %d, want 2", got)
+	}
+
+	os.Setenv("R2_KEEP_RUNS", "5")
+	if got := r2KeepRuns(); got != 5 {
+		t.Errorf("override = %d, want 5", got)
+	}
+
+	os.Setenv("R2_KEEP_RUNS", "0")
+	if got := r2KeepRuns(); got != 2 {
+		t.Errorf("invalid = %d, want 2 fallback", got)
+	}
+
+	os.Unsetenv("R2_KEEP_RUNS")
+}
+
+func TestR2MaxRetentionBytes(t *testing.T) {
+	os.Setenv("R2_MAX_RETENTION_BYTES", "")
+	if got := r2MaxRetentionBytes(); got != 10*1024*1024*1024 {
+		t.Errorf("default = %d, want 10GiB", got)
+	}
+
+	os.Setenv("R2_MAX_RETENTION_BYTES", "100")
+	if got := r2MaxRetentionBytes(); got != 100 {
+		t.Errorf("override = %d, want 100", got)
+	}
+
+	os.Setenv("R2_MAX_RETENTION_BYTES", "invalid")
+	if got := r2MaxRetentionBytes(); got != 10*1024*1024*1024 {
+		t.Errorf("invalid = %d, want 10GiB fallback", got)
+	}
+
+	os.Unsetenv("R2_MAX_RETENTION_BYTES")
+}
+
+func TestR2RunFromKey(t *testing.T) {
+	cases := []struct {
+		key string
+		run string
+		ok  bool
+	}{
+		{"hls/r-20260815T120000Z/seg-1.m4s", "r-20260815T120000Z", true},
+		{"hls/r-20260815T120000Z/init.mp4", "r-20260815T120000Z", true},
+		{"hls/playlist.m3u8", "", false},
+		{"hls/playlist.m3u8.tmp", "", false},
+		{"other/r-x/seg.m4s", "", false},
+		{"hls/r-noslash", "", false},
+	}
+	for _, c := range cases {
+		run, ok := r2RunFromKey(c.key)
+		if run != c.run || ok != c.ok {
+			t.Errorf("r2RunFromKey(%q) = (%q, %v), want (%q, %v)", c.key, run, ok, c.run, c.ok)
+		}
+	}
+}
+
+func TestCleanupOldRuns(t *testing.T) {
+	prevClient := r2Client
+	prevBucket := bucket
+	prevList := listObjects
+	prevDelete := deleteObjects
+	prevTotal := r2CleanupObjectsTotal
+	prevRuns := r2RunsRetained
+	prevBytes := r2BytesRetained
+	defer func() {
+		r2Client = prevClient
+		bucket = prevBucket
+		listObjects = prevList
+		deleteObjects = prevDelete
+		r2CleanupObjectsTotal = prevTotal
+		r2RunsRetained = prevRuns
+		r2BytesRetained = prevBytes
+	}()
+
+	bucket = "linearvoid-media"
+	r2Client = &s3.Client{}
+
+	size := int64(1024)
+	listObjects = func(_ *s3.Client, input *s3.ListObjectsV2Input) (*s3.ListObjectsV2Output, error) {
+		return &s3.ListObjectsV2Output{
+			Contents: []types.Object{
+				{Key: aws.String("hls/r-20260813T000000Z/seg-1.m4s"), Size: &size},
+				{Key: aws.String("hls/r-20260814T000000Z/seg-2.m4s"), Size: &size},
+				{Key: aws.String("hls/r-20260815T000000Z/seg-3.m4s"), Size: &size},
+				{Key: aws.String("hls/playlist.m3u8"), Size: &size},
+				{Key: aws.String("hls/playlist.m3u8.tmp"), Size: &size},
+			},
+			IsTruncated: aws.Bool(false),
+		}, nil
+	}
+
+	var deletedKeys []string
+	deleteObjects = func(_ *s3.Client, input *s3.DeleteObjectsInput) (*s3.DeleteObjectsOutput, error) {
+		for _, obj := range input.Delete.Objects {
+			deletedKeys = append(deletedKeys, aws.ToString(obj.Key))
+		}
+		return &s3.DeleteObjectsOutput{}, nil
+	}
+
+	n, err := cleanupOldRuns(context.Background())
+	if err != nil {
+		t.Fatalf("cleanupOldRuns error: %v", err)
+	}
+	if n != 1 {
+		t.Fatalf("deleted = %d, want 1 (oldest run)", n)
+	}
+
+	joined := strings.Join(deletedKeys, ",")
+	if !strings.Contains(joined, "hls/r-20260813T000000Z/seg-1.m4s") {
+		t.Fatalf("expected oldest run deleted, got: %v", deletedKeys)
+	}
+	if strings.Contains(joined, "playlist.m3u8") {
+		t.Fatalf("manifest must not be deleted: %v", deletedKeys)
+	}
+	if r2RunsRetained != 2 {
+		t.Fatalf("r2RunsRetained = %d, want 2", r2RunsRetained)
+	}
+	if r2BytesRetained != 2*size {
+		t.Fatalf("r2BytesRetained = %d, want %d", r2BytesRetained, 2*size)
+	}
+	if r2CleanupObjectsTotal != 1 {
+		t.Fatalf("r2CleanupObjectsTotal = %d, want 1", r2CleanupObjectsTotal)
+	}
+}
+
+func TestCleanupOldRuns_SizeCap(t *testing.T) {
+	prevClient := r2Client
+	prevBucket := bucket
+	prevList := listObjects
+	prevDelete := deleteObjects
+	prevTotal := r2CleanupObjectsTotal
+	prevRuns := r2RunsRetained
+	prevBytes := r2BytesRetained
+	defer func() {
+		r2Client = prevClient
+		bucket = prevBucket
+		listObjects = prevList
+		deleteObjects = prevDelete
+		r2CleanupObjectsTotal = prevTotal
+		r2RunsRetained = prevRuns
+		r2BytesRetained = prevBytes
+	}()
+
+	bucket = "linearvoid-media"
+	r2Client = &s3.Client{}
+
+	// Force a small cap so the size policy trims even the last 2 runs.
+	os.Setenv("R2_KEEP_RUNS", "2")
+	os.Setenv("R2_MAX_RETENTION_BYTES", "1024")
+	defer os.Unsetenv("R2_KEEP_RUNS")
+	defer os.Unsetenv("R2_MAX_RETENTION_BYTES")
+
+	size := int64(1024)
+	listObjects = func(_ *s3.Client, input *s3.ListObjectsV2Input) (*s3.ListObjectsV2Output, error) {
+		return &s3.ListObjectsV2Output{
+			Contents: []types.Object{
+				{Key: aws.String("hls/r-20260813T000000Z/seg-1.m4s"), Size: &size},
+				{Key: aws.String("hls/r-20260814T000000Z/seg-2.m4s"), Size: &size},
+				{Key: aws.String("hls/r-20260815T000000Z/seg-3.m4s"), Size: &size},
+			},
+			IsTruncated: aws.Bool(false),
+		}, nil
+	}
+
+	var deletedKeys []string
+	deleteObjects = func(_ *s3.Client, input *s3.DeleteObjectsInput) (*s3.DeleteObjectsOutput, error) {
+		for _, obj := range input.Delete.Objects {
+			deletedKeys = append(deletedKeys, aws.ToString(obj.Key))
+		}
+		return &s3.DeleteObjectsOutput{}, nil
+	}
+
+	n, err := cleanupOldRuns(context.Background())
+	if err != nil {
+		t.Fatalf("cleanupOldRuns error: %v", err)
+	}
+	// 3 runs -> keep 2 -> oldest deleted by count; remaining 2 bytes (2048) exceed
+	// the 1024 cap -> the older of the kept two is deleted, leaving only the newest.
+	if n != 2 {
+		t.Fatalf("deleted = %d, want 2", n)
+	}
+
+	joined := strings.Join(deletedKeys, ",")
+	if !strings.Contains(joined, "hls/r-20260813T000000Z/seg-1.m4s") {
+		t.Fatalf("expected oldest run deleted, got: %v", deletedKeys)
+	}
+	if !strings.Contains(joined, "hls/r-20260814T000000Z/seg-2.m4s") {
+		t.Fatalf("expected second-oldest run deleted by size cap, got: %v", deletedKeys)
+	}
+	if strings.Contains(joined, "hls/r-20260815T000000Z/seg-3.m4s") {
+		t.Fatalf("newest run must be kept, got: %v", deletedKeys)
+	}
+	if r2RunsRetained != 1 {
+		t.Fatalf("r2RunsRetained = %d, want 1", r2RunsRetained)
+	}
+}
+
+func TestPlaylistFingerprint(t *testing.T) {
+	tmpDir := t.TempDir()
+	p := filepath.Join(tmpDir, "playlist.txt")
+	if err := os.WriteFile(p, []byte("file '/app/media/a.mp4'\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	fp1, err := playlistFingerprint(p)
+	if err != nil {
+		t.Fatalf("playlistFingerprint error: %v", err)
+	}
+	fp2, err := playlistFingerprint(p)
+	if err != nil {
+		t.Fatalf("playlistFingerprint error: %v", err)
+	}
+	if fp1 != fp2 {
+		t.Errorf("fingerprint not stable: %q vs %q", fp1, fp2)
+	}
+
+	if err := os.WriteFile(p, []byte("file '/app/media/b.mp4'\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	fp3, err := playlistFingerprint(p)
+	if err != nil {
+		t.Fatalf("playlistFingerprint error: %v", err)
+	}
+	if fp1 == fp3 {
+		t.Errorf("fingerprint should change when playlist content changes")
+	}
+}
+
+func TestHLSNextStartNumber(t *testing.T) {
+	tmpDir := t.TempDir()
+	// Create segments 0..29 with a live window of 10.
+	for i := 0; i < 30; i++ {
+		if err := os.WriteFile(filepath.Join(tmpDir, fmt.Sprintf("seg-%06d.m4s", i)), []byte("x"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	next, err := hlsNextStartNumber(tmpDir, 10)
+	if err != nil {
+		t.Fatalf("hlsNextStartNumber error: %v", err)
+	}
+	if next != 30 {
+		t.Errorf("next = %d, want 30", next)
+	}
+
+	// Segments < 20 should be pruned; 20..29 kept (the live window).
+	for i := 0; i < 20; i++ {
+		if _, err := os.Stat(filepath.Join(tmpDir, fmt.Sprintf("seg-%06d.m4s", i))); !os.IsNotExist(err) {
+			t.Errorf("seg-%06d should have been pruned", i)
+		}
+	}
+	for i := 20; i < 30; i++ {
+		if _, err := os.Stat(filepath.Join(tmpDir, fmt.Sprintf("seg-%06d.m4s", i))); err != nil {
+			t.Errorf("seg-%06d should be kept: %v", i, err)
+		}
+	}
+}
+
+func TestLoadSharedHLSConfig(t *testing.T) {
+	prevDur := hlsSegmentDuration
+	prevWin := hlsWindowSize
+	defer func() {
+		hlsSegmentDuration = prevDur
+		hlsWindowSize = prevWin
+	}()
+
+	tmpDir := t.TempDir()
+	cfgPath := filepath.Join(tmpDir, "config.json")
+	if err := os.WriteFile(cfgPath, []byte(`{"hls_segment_duration":"4","hls_window_size":"12"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	os.Setenv("PLAYOUT_CONFIG_PATH", cfgPath)
+	defer os.Unsetenv("PLAYOUT_CONFIG_PATH")
+
+	loadSharedHLSConfig()
+
+	if hlsSegmentDuration != "4" {
+		t.Errorf("hlsSegmentDuration = %q, want 4", hlsSegmentDuration)
+	}
+	if hlsWindowSize != "12" {
+		t.Errorf("hlsWindowSize = %q, want 12", hlsWindowSize)
+	}
+}
+
+func TestLoadSharedHLSConfig_MissingFile(t *testing.T) {
+	prevDur := hlsSegmentDuration
+	prevWin := hlsWindowSize
+	defer func() {
+		hlsSegmentDuration = prevDur
+		hlsWindowSize = prevWin
+	}()
+
+	os.Setenv("PLAYOUT_CONFIG_PATH", filepath.Join(t.TempDir(), "nope.json"))
+	defer os.Unsetenv("PLAYOUT_CONFIG_PATH")
+
+	loadSharedHLSConfig() // should be a no-op without erroring
+
+	if hlsSegmentDuration != prevDur {
+		t.Errorf("hlsSegmentDuration changed to %q, want unchanged %q", hlsSegmentDuration, prevDur)
+	}
 }

backend/playout/start-playout.sh

@@ -3,8 +3,8 @@ set -e
 
 echo "=== Linear Void Playout Service Starting ==="
 echo "Playlist path: ${PLAYLIST_PATH:=/app/playlist/playlist.txt}"
-echo "HLS segment duration: ${HLS_SEGMENT_DURATION:-6}s"
-echo "HLS window size: ${HLS_WINDOW_SIZE:-24}"
+echo "HLS segment duration: ${HLS_SEGMENT_DURATION:-2}s"
+echo "HLS window size: ${HLS_WINDOW_SIZE:-12}"
 
 # Ensure playlist directory and file exist
 mkdir -p "$(dirname "$PLAYLIST_PATH")"
@@ -19,36 +19,13 @@ fi
 
 # Run normalization validation using the Go tool
 echo "Validating playlist and enforcing normalization (ADR-001/ADR-003)..."
-if ! /app/playlist-manager "$PLAYLIST_PATH"; then
+if ! /app/playlist-manager -validate "$PLAYLIST_PATH"; then
   echo "ERROR: Playlist validation failed. Check logs."
   exit 1
 fi
 
 echo "Playlist validated successfully. Starting continuous HLS playout..."
 
-mkdir -p /app/hls
-rm -f /app/hls/playlist.m3u8 /app/hls/init.mp4 /app/hls/segment_*.ts /app/hls/segment_*.m4s
-
-# Run FFmpeg in a loop for continuous playback
-while true; do
-  echo "[$(date)] Starting FFmpeg playout with browser-safe HLS encoding..."
-  ffmpeg -re -f concat -safe 0 -i "$PLAYLIST_PATH" \
-    -map 0:v:0 -map 0:a:0? \
-    -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,fps=30,format=yuv420p" \
-    -c:v libx264 -preset veryfast -pix_fmt yuv420p \
-    -profile:v high -level 4.0 \
-    -r 30 -g 60 -keyint_min 60 -sc_threshold 0 \
-    -c:a aac -ar 48000 -ac 2 -b:a 128k \
-    -f hls \
-    -hls_time "${HLS_SEGMENT_DURATION}" \
-    -hls_list_size "${HLS_WINDOW_SIZE}" \
-    -hls_segment_type fmp4 \
-    -hls_fmp4_init_filename init.mp4 \
-    -strftime 1 \
-    -hls_flags delete_segments+independent_segments \
-    -hls_segment_filename "/app/hls/segment_%Y%m%d_%H%M%S.m4s" \
-    "/app/hls/playlist.m3u8" || echo "FFmpeg exited with error (will restart in 5s per ADR-001 resilience requirements)..."
-
-  echo "Playout loop crashed or ended. Restarting in 5 seconds..."
-  sleep 5
-done
+# Single source of truth: the Go binary runs the full loop (HLS, R2 sync,
+# slate fallback, health server). The shell no longer duplicates the FFmpeg loop.
+exec /app/playlist-manager "$PLAYLIST_PATH"

docker-compose.prod.yml

@@ -168,6 +168,8 @@ services:
     command:
       - "--config.file=/etc/prometheus/prometheus.yml"
       - "--storage.tsdb.path=/prometheus"
+      - "--storage.tsdb.retention.time=30d"
+      - "--storage.tsdb.retention.size=15GB"
       - "--web.console.libraries=/etc/prometheus/console_libraries"
       - "--web.console.templates=/etc/prometheus/consoles"
       - "--web.enable-lifecycle"

docker-compose.yml

@@ -162,6 +162,8 @@ services:
     command:
       - "--config.file=/etc/prometheus/prometheus.yml"
       - "--storage.tsdb.path=/prometheus"
+      - "--storage.tsdb.retention.time=30d"
+      - "--storage.tsdb.retention.size=15GB"
       - "--web.console.libraries=/etc/prometheus/console_libraries"
       - "--web.console.templates=/etc/prometheus/consoles"
       - "--web.enable-lifecycle"

docs/DEPLOYMENT.md

@@ -14,6 +14,7 @@
   - [Target Topology](#target-topology)
   - [Prerequisites](#prerequisites)
   - [Environment File](#environment-file)
+    - [Gitea Secrets](#gitea-secrets)
   - [Pull-and-Run Deployment](#pull-and-run-deployment)
   - [First-Time or Recovery Provisioning](#first-time-or-recovery-provisioning)
   - [Health Verification](#health-verification)
@@ -72,7 +73,7 @@ Before the cutover in the plan above, treat the following as the minimum readine
 1. Verify the Hetzner host is reachable over SSH and Docker remote API TLS is working for the Gitea runner.
 2. Confirm all required production secrets are present under the `CI_PROD_*` prefix.
 3. Confirm `linearvoid.tv`, `www.linearvoid.tv`, and `media.linearvoid.tv` DNS targets are correct for the intended phase.
-4. Complete the manual Cloudflare/UptimeRobot checklist and attach evidence in `docs/operations/cloudflare-uptimerobot-checklist.md`.
+4. Complete the manual Cloudflare/UptimeRobot checklist and attach evidence in [Cloudflare Uptimerobot checklist](../docs/operations/cloudflare-uptimerobot-checklist.md).
 5. Run the production smoke path end to end: viewer SPA, HLS playback, chat connect, admin login, upload, playlist save, and playout health.
 6. Verify rollback is still possible before the final DNS switch.
 
@@ -93,11 +94,12 @@ Readiness is not complete until the checklist above and the manual evidence trac
 
 Three Gitea Actions workflows drive the full pipeline:
 
-| Workflow      | Trigger          | Purpose                                                                                  |
-| ------------- | ---------------- | ---------------------------------------------------------------------------------------- |
-| `ci.yml`      | Push to `main`   | Lint, build frontend, vet Go, build & push Docker images (`:latest`, `:main`)            |
-| `cd.yml`      | Push to `main`   | Deploy to test lab (`192.168.88.40:2375`) — runs **in parallel** with CI                 |
-| `release.yml` | Tag push `*.*.*` | Build & push versioned Docker images (`:X.Y.Z`, `:X.Y`, `:latest`), create Gitea Release |
+| Workflow             | Trigger           | Purpose                                                                                   |
+| -------------------- | ----------------- | ----------------------------------------------------------------------------------------- |
+| `ci.yml`             | Push to `main`    | Lint, build frontend, vet Go, build & push Docker images (`:latest`, `:main`)             |
+| `cd.yml`             | Push to `main`    | Deploy to test lab (`192.168.88.40:2375`) — runs **in parallel** with CI                  |
+| `release.yml`        | Tag push `*.*.*`  | Build & push versioned Docker images (`:X.Y.Z`, `:X.Y`, `:latest`), create Gitea Release  |
+| `workers-deploy.yml` | After CI succeeds | Deploy frontend to Cloudflare Workers (see `docs/operations/gitea-cloudflare-workers.md`) |
 
 CI and CD run simultaneously on every push to `main`. The deploy pulls whatever `:latest` images are available in the registry at that moment.
 
@@ -130,22 +132,48 @@ No code changes needed in the pipeline. See `DEPLOYMENT.md` Production Deploymen
 
 ## Environment File
 
-Use .env with at least:
+Use `.env` with at least:
 
-- CI_REGISTRY_URL
-- CI_REGISTRY_NAMESPACE
-- CHAT_PORT
-- NGINX_PORT
-- DATABASE_URL (if overridden)
-- REDIS_URL (if overridden)
-- ADMIN_USERNAME
-- ADMIN_PASSWORD
-- VITE_PUBLIC_APP_URL
-- VITE_PUBLIC_WS_URL
-- VITE_PUBLIC_HLS_URL
-- Cloudflare/R2 variables when media sync is enabled
+- `DATABASE_URL` — PostgreSQL connection string
+- `REDIS_URL` — Redis connection string
+- `ADMIN_USERNAME` / `ADMIN_PASSWORD` — admin dashboard credentials
+- `ADMIN_SESSION_TTL_HOURS` — session expiry (default 12)
+- `VITE_PUBLIC_APP_URL` / `VITE_PUBLIC_WS_URL` / `VITE_PUBLIC_HLS_URL` — frontend URLs
 
-See .env.example and SETUP.md for full variable reference.
+**Cloudflare R2 (required for HLS segment sync to edge):**
+
+- `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` — R2 write credentials
+- `R2_BUCKET_NAME` — bucket name (e.g. `linearvoid-media`)
+- `R2_ENDPOINT` — S3-compatible endpoint URL
+- `R2_REGION` — set to `auto`
+
+**Cloudflare (optional, for Workers):**
+
+- `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID`
+- `MEDIA_DOMAIN` — split media domain (e.g. `media.linearvoid.tv`)
+
+See `.env.example` and `SETUP.md` for full variable reference.
+
+### Gitea Secrets
+
+The CD workflow (`cd.yml`) injects sensitive values from Gitea secrets into the `.env` file at deploy time. The following secrets must be configured in the Gitea repository:
+
+| Secret Name                  | Description                       |
+| ---------------------------- | --------------------------------- |
+| `DATABASE_URL`               | PostgreSQL connection string      |
+| `ADMIN_USERNAME`             | Admin dashboard username          |
+| `ADMIN_PASSWORD`             | Admin dashboard password          |
+| `R2_ACCESS_KEY_ID`           | Cloudflare R2 access key          |
+| `R2_SECRET_ACCESS_KEY`       | Cloudflare R2 secret key          |
+| `R2_BUCKET_NAME`             | R2 bucket name                    |
+| `R2_ENDPOINT`                | R2 S3-compatible endpoint URL     |
+| `R2_ADMIN_ACCESS_KEY_ID`     | R2 admin access key (optional)    |
+| `R2_ADMIN_SECRET_ACCESS_KEY` | R2 admin secret key (optional)    |
+| `R2_ADMIN_ENDPOINT`          | R2 admin endpoint (optional)      |
+| `CLOUDFLARE_API_TOKEN`       | Cloudflare API token (optional)   |
+| `CLOUDFLARE_ACCOUNT_ID`      | Cloudflare account ID (optional)  |
+| `CI_REGISTRY_USER`           | Gitea container registry username |
+| `CI_REGISTRY_TOKEN`          | Gitea container registry token    |
 
 ## Pull-and-Run Deployment
 
@@ -265,7 +293,7 @@ docker compose -f docker-compose.prod.yml down -v
 
 ## Nginx and Proxy Considerations
 
-- If an external proxy (for example Nginx Proxy Manager) fronts the stack, align request body limits with internal nginx.
+- If an external proxy (for example Nginx Proxy Manager) fronts the stack, align request body limits with internal nginx, see [nginx.conf](../infrastructure/nginx/nginx.conf).
 - For resumable admin uploads, ensure client_max_body_size supports chunk requests in both proxy layers.
 
 ## Security Baseline

docs/DEVELOPMENT.md

@@ -1,95 +0,0 @@
-# DEVELOPMENT.md — Linear Void Remaining Tasks
-
-## Test Fixtures (COMPLETE)
-
-- [x] Create test media fixtures in `backend/playout/testdata/`:
-  - `valid_720p30.mp4` — small (1-2s) H.264/AAC compliant file
-  - `invalid_h265.mp4` — wrong codec
-  - `invalid_24fps.mp4` — wrong framerate
-  - Generate via `ffmpeg` commands documented in test file headers
-  - Windows dev path: `C:\Users\zwits\AppData\Local\Microsoft\WinGet\Packages\Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe\ffmpeg-9.0-full_build\bin\ffmpeg.exe`
-
-- [x] Create test playlist fixtures in `backend/playout/testdata/`:
-  - `valid_playlist.txt`, `empty_playlist.txt`, `comments_only.txt`, `mixed_valid_invalid.txt`
-
-- [x] Document ffmpeg fixture-generation commands in `playlist_test.go` header
-
-## User Frontend Tests (PARTIALLY COMPLETE)
-
-- [x] Video player behavior (play, pause, seek, buffering, error handling) - HLS player startup, native/fallback, URL resolution covered
-- [x] Chat functionality (send/receive messages, presence, rate limiting, moderation) - send, receive, presence join/leave, DM flow, reconnect covered
-- [ ] State management and data flow
-- [ ] Responsive design and layout across different screen sizes
-- [ ] Accessibility testing (keyboard navigation, screen reader support)
-- [x] Integration with backend APIs (mocking API responses for testing)
-- [ ] Test coverage for all critical frontend components and interactions
-- [ ] Add code coverage reporting and enforce minimum coverage threshold in CI/CD pipeline
-- [ ] Document test cases and expected outcomes
-
-## Admin Frontend Tests (PARTIALLY COMPLETE)
-
-- [x] Playlist management UI (add/remove videos, reorder, normalize) - save/error handling, sortable rendering
-- [ ] User moderation tools (mute/ban/report users, view moderation logs)
-- [x] Metrics and monitoring dashboards (Prometheus/Grafana integration) - overview + analytics rendering
-- [ ] State management and data flow
-- [ ] Responsive design and layout across different screen sizes
-- [ ] Accessibility testing (keyboard navigation, screen reader support)
-- [x] Integration with backend APIs (mocking API responses for testing)
-- [ ] Test coverage for all critical admin UI components and interactions
-- [ ] Add code coverage reporting and enforce minimum coverage threshold in CI/CD pipeline
-- [ ] Document test cases and expected outcomes
-
-## Cloudflare R2 Integration Test (PARTIALLY COMPLETE)
-
-- [x] Upload test HLS segments and manifests to R2 bucket (SyncToR2 with mock, verified bucket/key/body)
-- [x] Verify correct cache headers are applied (immutable segments via segmentCacheControl, short-lived manifests via manifestCacheControl)
-- [ ] Test retrieval of segments and manifests from R2 via Cloudflare edge
-- [ ] Validate cache hit/miss behavior and performance metrics
-- [x] Ensure integration test can run in CI/CD pipeline with proper mocking/stubbing of R2 API (putObject mock, no network calls)
-- [x] Document test cases and expected outcomes (TestSyncToR2 + TestSyncToR2_ManifestCacheHeaders + TestSyncToR2_NoCacheHeadersForUnknownExt)
-- [x] Document required stubs or mocks (putObject variable injection pattern)
-
-## Cloudflare Configuration (manual — Cloudflare dashboard)
-
-> Evidence tracker: `docs/operations/cloudflare-uptimerobot-checklist.md`
-
-- [ ] Cloudflare Pages: link Gitea repo, build `cd frontend && npm run build`, output `frontend/dist`
-- [ ] Tiered Cache: enable Smart Tiered Cache, validate `Cf-Cache-Status: HIT` from upper tier
-- [ ] WAF: enable OWASP Managed Ruleset, set to Simulate → review 48h → Block, enable Bot Fight Mode
-- [ ] Rate limiting: `/api/admin/login` + `/api/admin/*` → 10 req/10s per IP, Challenge action
-- [ ] HTTPS/WSS: Always Use HTTPS, HSTS max-age=31536000 includeSubDomains preload, min TLS 1.2
-- [ ] HTTPS/WSS: enforce at edge (Cloudflare) and origin (nginx), redirect HTTP → HTTPS
-
-## External Services
-
-> Evidence tracker: `docs/operations/cloudflare-uptimerobot-checklist.md`
-
-- [ ] UptimeRobot: add HTTP monitor for `https://linearvoid.tv/health` (5min interval)
-- [ ] UptimeRobot: add keyword monitor for `https://linearvoid.tv/hls/playlist.m3u8` (keyword: `#EXTM3U`, 5min)
-- [ ] Alert on 2 consecutive failures, notify via email + Discord/Slack webhook
-
-## Production Deployment (Hetzner — not provisioned)
-
-- [ ] Provision Hetzner CX22 (2 vCPU, 4 GB, 40 GB) in Ashburn VA, Ubuntu 24.04
-- [ ] Install Docker Engine + Compose plugin, open firewall: 80/443 (public), 2375 (runner IP only)
-- [ ] Configure Docker daemon for remote TLS access (`-H tcp://0.0.0.0:2376` with certs)
-- [ ] Create `/srv/linearvoid/data/{playlist,media,hls,chat,slate}` directories
-- [ ] Add `CI_PROD_*` secrets to Gitea: DOCKER_HOST, R2 keys, admin password, DB password, Grafana password
-- [ ] Trigger CD workflow with `DOCKER_HOST` pointing to Hetzner IP
-- [ ] Verify all 11 containers start healthy, check `/health`, `/hls/playlist.m3u8`, WebSocket
-- [ ] Update Cloudflare A record `linearvoid.tv` → Hetzner IP, SSL Full (strict), test HTTPS + WSS
-- [ ] Smoke test: viewer SPA loads, HLS plays, chat connects, admin login → upload → playlist → playout
-- [ ] Set up Prometheus alerting notifications + UptimeRobot on production URL
-- [ ] Run `scripts/backup-db.sh` + `scripts/verify-backups.sh` on production host
-- [ ] Document production IP, SSH access, rollback procedure, scaling thresholds
-
-## Scaling & Performance (planning only)
-
-- [ ] Tune manifest TTL: measure `Cf-Cache-Status` distribution, adjust to 0.5× segment duration
-- [ ] Measure TTFB: WebPageTest from 3+ US regions, target <4s warm cache, document baseline
-- [ ] Load-test WebSocket: `artillery` or Go script, ramp 10→100→500→1000 connections, measure p95 latency + errors (scaffolding complete; benchmark execution pending)
-- [ ] Benchmark admin API: `wrk`/`k6` against `/api/admin/*`, target p95 <1s, identify slow queries (scaffolding complete; benchmark execution pending)
-- [ ] Track cache hit ratio: Cloudflare GraphQL → Grafana panel, alert <90%
-- [ ] Capacity triggers: Prometheus rules for cache-miss >10%/15min, chat p95 >1s/5min, CPU >80%/10min, Redis memory >85%/10min
-- [ ] Phase 2 plan: document boundaries (playout CPU, chat latency, DB state, monitoring), estimate per-service resources
-- [ ] Phase 3 plan: research second Hetzner location, design warm standby + DNS failover + DB/Redis replication

docs/MONITORING.md

@@ -52,6 +52,12 @@ Config: `monitoring/prometheus/prometheus.yml` (15s scrape interval)
 - **Linear Void app**: `monitoring/grafana/dashboard.json` — clients, messages, moderation, Redis, sessions, scrape health
 - **Prometheus ops**: `monitoring/grafana/dashboards/dashboard.json` — TSDB, CPU/memory, WAL, compactions, query latency
 
+## Metrics checking
+
+See detailed scripts for querying Prometheus scrape targets:
+
+- [Linux/macOS](./infrastructure/monitoring/prometheus_curl.md)
+
 ## Key Metrics
 
 - `linearvoid_chat_connected_clients` — active WebSocket connections
@@ -89,3 +95,4 @@ Config: `monitoring/prometheus/prometheus.yml` (15s scrape interval)
 - Keep alert thresholds tied to actual user impact.
 - Review dashboards after each release that changes endpoints or metrics names.
 - Periodically test alert routing and incident response flow.
+- Metrics retention is set to **30 days** time-based plus a **15GB** size cap (`--storage.tsdb.retention.time=30d --storage.tsdb.retention.size=15GB` on the `prometheus` service in `docker-compose.yml` and `docker-compose.prod.yml`). Increase the size cap before extending the time window so the TSDB does not hit the disk limit first.

docs/README.md

@@ -6,6 +6,14 @@ This folder contains the documentation for the Linear Void project. The document
 
 - [Architecture](architecture/README.md) - High-level system architecture and component interactions.
 
+## Infrastructure
+
+- Cloudflare
+  - [Cache Rules](./infrastructure/cloudflare/cache-rules.md) - Cache rules for Cloudflare Workers.
+  - [Account Troubleshooting](./infrastructure/cloudflare/cloudflare-account-troubleshooting.md) - Troubleshooting Cloudflare account issues.
+- Monitoring
+  - [Prometheus CURL](./infrastructure/monitoring/prometheus_curl.md) - Prometheus metrics endpoint testing with curl and jq. Doocumentation of available metrics and their meanings.
+
 ## API
 
 - [API](API.md) - Implemented WebSocket and REST API reference.
@@ -30,12 +38,18 @@ This folder contains the documentation for the Linear Void project. The document
 
 - [Streaming](STREAMING.md) - Streaming architecture, playout, and delivery details.
 
-## Development
-
-- [Development](DEVELOPMENT.md) - Remaining tasks and test fixtures for development.
-
 ## Additional Resources
 
 - [Marketing](marketing/README.md) - Marketing materials and resources.
 - [Operations](operations/README.md) - Operational procedures and checklists.
 - [Incident Runbook](incident-runbook.md) - Incident response and disaster recovery procedures.
+
+## Other Documents
+
+- [CHANGELOG](../CHANGELOG.md) - Release notes and version history.
+- [CONTRIBUTING](../CONTRIBUTING.md) - Contribution guidelines and code of conduct.
+- [TODO](../.github/instructions/TODO.md) - Active implementation plan with checkboxes.
+- [Backlog](../.github/instructions/BACKLOG.md) - Consolidated list of all development tasks.
+- [Agents](../.github/AGENTS.md) - Instructions for agents and task management.
+- [Memory](../.github/MEMORY.md) - Session memory and development progress tracking.
+- [README](../README.md) - Project overview and high-level information.

docs/SETUP.md

@@ -1,13 +1,15 @@
 # Linear Void Setup Guide
 
+**Last Updated**: 2026-08-03
+
 This guide covers prerequisites, environment setup, running the application locally and in production, and troubleshooting. It references the [architecture documentation](./docs/architecture/README.md)(`docs/architecture/README.md`).
 
 ## Prerequisites
 
 - **Docker & Docker Compose**: Required for running the full stack (playout, chat, nginx, redis, db, prometheus, grafana). Install from [docker.com](https://www.docker.com).
-- **Node.js 20+**: Required for frontend development and production builds (`cd frontend && npm install && npm run build`).
+- **Node.js 22+**: Required for frontend development and production builds (`cd frontend && npm install && npm run build`).
 - **npm**: Installed with Node.js and used for the frontend dependency installation and Vite workflow.
-- **Go 1.23+**: Recommended when working on the Go services outside Docker (`backend/chat`, `backend/playout`).
+- **Go 1.25+**: Recommended when working on the Go services outside Docker (`backend/chat`, `backend/playout`).
 - **FFmpeg**: Used by the playout service for HLS generation. Install via `apt install ffmpeg` (Linux), Homebrew (macOS), or Winget (Windows).
 - **Git**: For cloning and version control.
 - **Cloudflare Account**: For R2 storage and CDN (free tier sufficient for most use cases).
@@ -81,70 +83,7 @@ flowchart LR
    cp .env.example .env
    ```
 
-3. **Configure `.env`** (edit with your values):
-
-   ```env
-   # Cloudflare R2 (required for video storage and $0 egress)
-   R2_ACCESS_KEY_ID=your-r2-access-key
-   R2_SECRET_ACCESS_KEY=your-r2-secret-key
-   R2_BUCKET_NAME=linearvoid-media
-   R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
-   R2_REGION=auto
-
-   # Cloudflare (for custom domain and cache rules)
-   CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
-   CLOUDFLARE_ACCOUNT_ID=your-account-id
-   MEDIA_DOMAIN=media.linearvoid.tv
-
-   # Public frontend URLs
-   # Preferred local setup uses the real public domains through Cloudflare and Nginx Proxy Manager.
-   VITE_PUBLIC_APP_URL=https://linearvoid.tv
-   VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws
-   VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8
-   VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR=admin
-   VITE_PUBLIC_ADMIN_DEFAULT_ROOM=main
-   VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT=50
-   ADMIN_USERNAME=admin
-   ADMIN_PASSWORD=change-me
-   ADMIN_SESSION_TTL_HOURS=12
-   # Optional direct-local fallback when bypassing the public proxy:
-   # VITE_PUBLIC_APP_URL=http://localhost
-   # VITE_PUBLIC_WS_URL=ws://localhost/ws
-   # VITE_PUBLIC_HLS_URL=http://localhost/hls/playlist.m3u8
-
-   # Gitea Container Registry (for self-hosted Docker images)
-   CI_REGISTRY_URL=git.allucanget.biz
-   CI_REGISTRY_USER=your-gitea-username
-   CI_REGISTRY_TOKEN=your-gitea-token
-   CI_REGISTRY_NAMESPACE=zwitschi/linearvoid
-   # Gitea API access (optional, for CI/release automation)
-   CI_SERVER_URL=https://git.allucanget.biz
-
-   # Chat / Database
-   DATABASE_URL=postgres://linearvoid:linearvoid@db:5432/linearvoid?sslmode=disable
-   # or for SQLite-only local development:
-   # DATABASE_URL=sqlite://./data/chat.db
-   REDIS_URL=redis://redis:6379/0
-
-   # Ports (for local development)
-   PLAYOUT_PORT=8080
-   CHAT_PORT=3000
-   NGINX_PORT=80
-
-   # Playout Configuration
-   PLAYLIST_PATH=/app/playlist.txt
-   HLS_SEGMENT_DURATION=6
-   HLS_WINDOW_SIZE=24
-
-   # Logging / Monitoring
-   LOG_LEVEL=info
-   PROMETHEUS_PORT=9090
-   GRAFANA_PORT=3001
-
-   # Development flags
-   NODE_ENV=development
-   GO_ENV=development
-   ```
+3. **Configure `.env`** (copy from `.env.example` and replace placeholders)
 
 4. **Check local value overrides for Docker Compose**:
    - `docker-compose.yml` builds images locally and maps the frontend build output from `frontend/dist` into nginx.
@@ -223,24 +162,40 @@ flowchart LR
    - Use Cloudflare proxied DNS with Full (strict) TLS so browser traffic uses `https://linearvoid.tv`, `wss://linearvoid.tv/ws`, and `https://media.linearvoid.tv`.
 
 6. **Apply cache behavior**:
-   - Configure the `.m4s` and `.m3u8` cache rules from `infrastructure/cloudflare/cache-rules.md`.
+   - Configure the `.m4s` and `.m3u8` cache rules from [cache-rules](../docs/infrastructure/cloudflare/cache-rules.md).
    - Enable Smart Tiered Cache for the R2-backed hostname.
    - If you need header normalization for immutable segment caching, deploy `infrastructure/cloudflare/worker.js` to the same zone.
 
-7. **Verify access**:
+7. **Configure R2 CORS**:
+   - Add CORS rules to allow the app domain to access the R2 bucket for HLS delivery.
+   - Example CORS configuration:
+
+   ```json
+   [
+     {
+       "AllowedOrigins": ["https://linearvoid.tv"],
+       "AllowedMethods": ["GET"],
+       "AllowedHeaders": ["*"],
+       "ExposeHeaders": ["ETag", "Cache-Control"],
+       "MaxAgeSeconds": 3600
+     }
+   ]
+   ```
+
+8. **Verify access**:
    - Confirm uploads with an S3-compatible client such as `aws s3 ls --endpoint-url <R2_ENDPOINT>`.
    - After deployment, check Cloudflare analytics for cache hit ratio and origin request volume.
 
 ## Cloudflare
 
-Use this section for full edge setup (DNS, Pages, cache, security, and monitoring).
+Use this section for full edge setup (DNS, Workers, cache, security, and monitoring).
 
 Execution tracker: `docs/operations/cloudflare-uptimerobot-checklist.md`.
 
 ### 1. DNS Setup
 
-1. Add apex record for `linearvoid.tv` pointing to Cloudflare Pages target.
-2. Add `www` CNAME to Cloudflare Pages and configure redirect to `https://linearvoid.tv`.
+1. Add apex record for `linearvoid.tv` pointing to the Cloudflare Worker.
+2. Add `www` CNAME to the Cloudflare Worker and configure redirect to `https://linearvoid.tv`.
 3. Add `media.linearvoid.tv` for split-domain HLS delivery.
 4. Keep all records proxied (orange cloud) unless troubleshooting requires DNS-only mode.
 
@@ -249,7 +204,8 @@ Execution tracker: `docs/operations/cloudflare-uptimerobot-checklist.md`.
 1. Create bucket `linearvoid-media`.
 2. Set location hint to `enam` (US-East).
 3. Attach custom domain `media.linearvoid.tv` to the bucket.
-4. Verify object read works from the custom domain.
+4. Configure CORS rules to allow `https://linearvoid.tv` for HLS delivery.
+5. Verify object read works from the custom domain.
 
 ### 3. Cache Rules
 
@@ -272,24 +228,23 @@ Configure Cloudflare Cache Rules:
 4. Validate behavior using response headers:
    - `Cf-Cache-Status` should move from `MISS` to `HIT` for hot objects
 
-Reference: `infrastructure/cloudflare/cache-rules.md`.
+Reference: [cache-rules](../docs/infrastructure/cloudflare/cache-rules.md).
 
-### 4. Cloudflare Pages
+### 4. Cloudflare Workers
 
-1. Connect Gitea repository to Cloudflare Pages.
-2. Build command:
+Also see [the automated Gitea Actions deployment guide](./operations/gitea-cloudflare-workers.md).
+
+Manual setup:
+
+1. Create a Cloudflare Worker for the static SPA (Workers & Pages → Create → Worker).
+2. Build the frontend:
 
    ```bash
    cd frontend && npm run build
    ```
 
-3. Output directory:
-
-   ```text
-   frontend/dist
-   ```
-
-4. Configure production domain to `linearvoid.tv`.
+3. Bind the build output (`frontend/dist`) as Worker static assets.
+4. Configure production domain `linearvoid.tv` on the Worker.
 
 ### 5. Tiered Cache
 
@@ -346,7 +301,7 @@ Create external monitors:
 ### 10. Verification Checklist
 
 1. DNS resolves for `linearvoid.tv`, `www.linearvoid.tv`, and `media.linearvoid.tv`.
-2. Pages serves frontend for apex and `www` redirects correctly.
+2. Workers serve frontend for apex and `www` redirects correctly.
 3. HLS segments are cacheable long-term, manifests refresh every ~2s.
 4. Admin paths are rate-limited and WAF events are visible.
 5. HTTPS and WSS both succeed with valid certificates.
@@ -553,7 +508,7 @@ To allow the Gitea Actions runner (or your local machine) to deploy to the remot
 1. **Provision VPS**: Use Hetzner Cloud CX22 in Ashburn, VA (per ADR-001).
 2. **Configure Cloudflare**:
    - Create R2 bucket with `enam` location hint.
-   - Set up custom media domain (`media.linearvoid.tv`) with the cache rules from `infrastructure/cloudflare/cache-rules.md`.
+   - Set up custom media domain (`media.linearvoid.tv`) with the cache rules from [cache-rules](../docs/infrastructure/cloudflare/cache-rules.md).
    - Point `linearvoid.tv` and `www.linearvoid.tv` at the app entrypoint, then redirect `www` to the apex domain.
    - Use Full (strict) TLS for both app and media hostnames.
    - Apply the Worker from `infrastructure/cloudflare/worker.js` for advanced header management.
@@ -584,5 +539,3 @@ See `docs/architecture/README.md` for the full arc42 documentation and the ADRs
 - Project Structure: Root `README.md`.
 
 The system is ready for use. For production, review ADR-001 for cost estimates and scaling guidance.
-
-**Last Updated**: 2026-08-03

docs/STREAMING.md

@@ -5,7 +5,7 @@ This document is the operational contract for Linear Void video ingest, playout,
 ## Production flow
 
 ```mermaid
-flowchart LR
+flowchart TD
     A["Normalized MP4 assets"] --> B["Playlist and schedule"]
     B --> C["Playout service and FFmpeg"]
     C --> D["Local HLS staging"]
@@ -68,13 +68,15 @@ Baseline packaging:
 | ---------------- | ------------------------------------------------------------------------------------- |
 | Protocol         | Standard live HLS, not LL-HLS                                                         |
 | Segment format   | fMP4 (`.m4s`) with an initialization segment; `.ts` may be supported during migration |
-| Segment target   | 6 seconds (`HLS_SEGMENT_DURATION=6`)                                                  |
-| Live window      | 24 segments (`HLS_WINDOW_SIZE=24`), about 144 seconds                                 |
+| Segment target   | 2 seconds (`HLS_SEGMENT_DURATION=2`)                                                  |
+| Live window      | 12 segments (`HLS_WINDOW_SIZE=12`), about 24 seconds                                  |
 | Codec path       | Stream copy for conforming assets; no per-viewer transcoding                          |
 | Expected latency | 15–35 seconds                                                                         |
 
 Segment boundaries must align with keyframes. Timestamps must remain monotonic across item boundaries. If FFmpeg cannot preserve a seamless timeline, insert `#EXT-X-DISCONTINUITY` and publish the corresponding new initialization segment.
 
+**Segment duration rationale**: 2s segments were chosen to lower end-to-end latency and keep the live window small (12 × 2s = 24s) while staying well above the manifest TTL (1–2s). The 2s GOP (30fps, `-g 60 -keyint_min 60`) already matches the target, so segments cut cleanly on keyframes. Longer durations (4–6s) increase latency and window depth; shorter than 2s inflates segment/request overhead and R2 Class B operations with little latency gain.
+
 Every segment name is globally unique and never reused, including after a restart or playlist loop. Use a run/session ID plus a monotonically increasing media sequence, for example:
 
 ```text
@@ -128,6 +130,8 @@ The manifest must refresh within a few seconds. Repeated segment requests should
 
 The SPA uses native HLS where supported and hls.js elsewhere.
 
+- Firefox has no native HLS, so it uses the hls.js/MSE path; fMP4 (`.m4s` + init segment) is supported. Autoplay requires `muted` + `playsinline`, which are already set on the `<video>` element.
+
 - Start at the live edge with a conservative buffer; do not seek to playlist start.
 - Treat the manifest as the synchronization source and target roughly three segments behind the newest segment unless testing supports a smaller margin.
 - Recover transient network/media errors with bounded retries and exponential backoff.
@@ -171,11 +175,13 @@ A release is streaming-ready only when one full playlist boundary has played wit
 | Variable                                   | Purpose                                            |
 | ------------------------------------------ | -------------------------------------------------- |
 | `PLAYLIST_PATH`                            | Active playlist file                               |
-| `HLS_SEGMENT_DURATION`                     | Target segment duration; baseline `6`              |
-| `HLS_WINDOW_SIZE`                          | Manifest window; baseline `24`                     |
+| `HLS_SEGMENT_DURATION`                     | Target segment duration; baseline `2`              |
+| `HLS_WINDOW_SIZE`                          | Manifest window; baseline `12`                     |
 | `R2_ENDPOINT`, `R2_REGION`                 | S3-compatible publication endpoint                 |
 | `R2_BUCKET_NAME`                           | Media bucket                                       |
 | `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` | Write credentials, available only to the publisher |
+| `R2_KEEP_RUNS`                             | Number of run folders to retain (default `2`)      |
+| `R2_MAX_RETENTION_BYTES`                   | Max bytes retained across run folders (10 GiB)     |
 | `MEDIA_DOMAIN`                             | Public R2 custom domain                            |
 | `VITE_PUBLIC_HLS_URL`                      | Public live manifest URL                           |
 

docs/architecture/README.md

@@ -39,7 +39,9 @@
     - [Video Normalization \& Playout](#video-normalization--playout)
       - [Required Source Profile (Linear Void v1)](#required-source-profile-linear-void-v1)
       - [Reference Normalization Command](#reference-normalization-command)
-      - [Verification Gate (ffprobe)](#verification-gate-ffprobe)
+      - [Automatic Normalization \& Verification (ffprobe)](#automatic-normalization--verification-ffprobe)
+    - [Runtime Configuration Store](#runtime-configuration-store)
+    - [Analytics (Matomo)](#analytics-matomo)
     - [Monitoring \& Resilience](#monitoring--resilience)
       - [Prometheus Baseline](#prometheus-baseline)
       - [Grafana Dashboards](#grafana-dashboards)
@@ -48,6 +50,7 @@
       - [Chat WebSocket API](#chat-websocket-api)
       - [Playout and Delivery REST API](#playout-and-delivery-rest-api)
       - [Admin REST API](#admin-rest-api)
+      - [Viewer REST API](#viewer-rest-api)
     - [Cloudflare Configuration Reference](#cloudflare-configuration-reference)
       - [DNS and Zone Routing](#dns-and-zone-routing)
       - [Cache Rules Baseline](#cache-rules-baseline)
@@ -58,6 +61,7 @@
       - [Transport and Edge Protection](#transport-and-edge-protection)
       - [Reverse Proxy Enforcement (nginx)](#reverse-proxy-enforcement-nginx)
       - [Admin Authentication and Session Security](#admin-authentication-and-session-security)
+      - [Viewer User Accounts](#viewer-user-accounts)
       - [Rate Limiting and Abuse Controls](#rate-limiting-and-abuse-controls)
       - [CORS and Cross-Origin Behavior](#cors-and-cross-origin-behavior)
       - [Moderation and Privacy](#moderation-and-privacy)
@@ -87,12 +91,7 @@
 
 ## Companion Documentation
 
-- [API.md](../API.md) - Implemented WebSocket and REST API reference.
-- [DEPLOYMENT.md](../DEPLOYMENT.md) - Production deployment and operational runbook.
-- [MONITORING.md](../MONITORING.md) - Metrics, dashboards, and monitoring troubleshooting.
-- [SECURITY.md](../SECURITY.md) - Security model, controls, and hardening baseline.
-- [SETUP.md](../SETUP.md) - Test lab setup, local development, and CI/CD workflow.
-- [STREAMING.md](../STREAMING.md) - Streaming architecture, playout, and delivery details.
+see [Documentation README](../README.md) for an overview of all documentation, including architecture, ADRs, operational procedures, and setup guides.
 
 ## Introduction and Goals
 
@@ -165,7 +164,7 @@ flowchart TD
 
     subgraph "Cloudflare Global Edge"
         CDN[Cloudflare CDN<br/>Cache Rules + WAF + TLS]
-        Pages[Cloudflare Pages<br/>Static SPA Hosting]
+        Workers[Cloudflare Workers<br/>Static SPA Hosting]
         R2[Cloudflare R2<br/>HLS Segments + Source MP4s<br/>enam location hint]
     end
 
@@ -178,17 +177,17 @@ flowchart TD
     Admins -->|HTTPS - Schedule/Playlist| Playout
     Playout -->|S3-compatible Upload| R2
     R2 -->|Cached HLS| CDN
-    Viewers -->|HTTPS| Pages
+    Viewers -->|HTTPS| Workers
     Viewers -->|HLS Requests| CDN
     Viewers -->|WSS Chat| Chat
     Chat --> VPS
-    VPS -->|Proxy / Static| Pages
+    VPS -->|Proxy / Static| Workers
     CDN -->|Origin Pull on Miss| R2
 ```
 
 **External Interfaces**:
 
-- **Cloudflare**: CDN (cache rules for `.m4s` and `.ts` vs `.m3u8`), R2 (object storage, $0 egress), Pages (static hosting), WAF/TLS.
+- **Cloudflare**: CDN (cache rules for `.m4s` and `.ts` vs `.m3u8`), R2 (object storage, $0 egress), Workers (static hosting), WAF/TLS.
 - **Hetzner VPS**: Compute for playout and chat (low-cost US-East with good peering).
 - **Browsers**: Native HLS (`<video>` + hls.js) and WebSocket APIs.
 - **Source**: Pre-normalized MP4 files uploaded to R2.
@@ -234,7 +233,7 @@ graph TD
     subgraph Cloudflare
         CDN[CDN + Cache Rules<br/>.m4s and .ts immutable long TTL<br/>.m3u8 short TTL]
         R2[R2 - HLS + Source]
-        Pages[Pages - Static SPA]
+        Workers[Workers - Static SPA]
     end
     VPS[VPS Hetzner Ashburn]
     Playout[FFmpeg + MediaMTX/SRS<br/>Playlist → HLS]
@@ -245,7 +244,7 @@ graph TD
     Admin --> Playout
     Playout --> R2
     R2 --> CDN
-    Viewer --> Pages
+    Viewer --> Workers
     Viewer --> CDN
     Viewer --> Chat
     Chat --> VPS
@@ -275,7 +274,7 @@ graph TB
     subgraph "Cloudflare Edge"
         CF[CDN + WAF<br/>Cache Rules]
         R2[R2 Bucket<br/>media + HLS]
-        PAGES[Pages<br/>SPA hosting]
+        WORKERS[Workers<br/>SPA hosting]
     end
 
     subgraph "Docker Host (Hetzner CX22)"
@@ -310,7 +309,10 @@ graph TB
 - **Input**: `data/playlist/playlist.txt` — ordered list of MP4 file paths
 - **Output**: HLS segments (`.m4s` and `.ts`) + live manifest (`.m3u8`) written to `data/hls/`, mirrored to R2
 - **Resilience**: Restart counter (>5/60s → activate slate), Prometheus metrics on port 8081
-- **Validation**: ffprobe gate on all ingested files (codec, fps, resolution, keyframe interval)
+- **Validation**: ffprobe gate on all ingested files (codec, fps, resolution, keyframe interval); `-validate` mode checks the playlist without running the loop
+- **Seamless looping**: Only resets HLS output when the playlist fingerprint (SHA-256) changes, on crash/slate recovery, or first run; otherwise continues segment numbering via `-start_number`
+- **R2 retention**: `cleanupOldRuns` keeps the newest `R2_KEEP_RUNS` run folders (default 2) and caps retained data at `R2_MAX_RETENTION_BYTES` (default 10 GiB), triggered after each run plus an hourly backstop
+- **Shared config**: Reads the runtime `config.json` (`loadSharedHLSConfig`) as an env fallback for HLS segment duration/window
 
 #### Chat Service (`backend/chat/src/main.go`)
 
@@ -339,50 +341,57 @@ Module-level breakdown per service.
 
 #### Chat Service Modules
 
-| Module                 | File/Lines                                                     | Responsibility                                                                           |
-| ---------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| **Connection Manager** | `main.go` (hub, clients map)                                   | Track active WebSocket connections per room, fan-out messages                            |
-| **Message Parser**     | `main.go` (readPump, handleMessage)                            | Parse JSON envelope `{type, room?, ...}`, validate fields, route to handler              |
-| **Room Registry**      | `main.go` (rooms map, room broadcasts)                         | Map room name → client set, handle join/leave/close                                      |
-| **DM Router**          | `main.go` (handleDirectMessage)                                | Resolve target user in clients map, deliver private message                              |
-| **Persistence Layer**  | `main.go` (GORM models: Message, DirectMessage, ModerationLog) | Store/retrieve chat messages, DMs, moderation events                                     |
-| **Redis Subsystem**    | `main.go` (redisClient, rate limiting, pub/sub, presence)      | INCR+EXPIRE rate limit, SETEX presence, PSUBSCRIBE room fan-out                          |
-| **Auth Handler**       | `main.go` (handleAdminLogin, adminAuthMiddleware)              | Session cookie creation/validation, login rate limiting                                  |
-| **Admin API Router**   | `main.go` (handleAdmin\*)                                      | Upload, playlist CRUD, schedule overrides, moderation actions, analytics, system summary |
-| **Metrics Exporter**   | `main.go` (prometheus.MustRegister)                            | Expose connected_clients, messages_total, dms_total, moderation_actions, redis_up        |
+| Module                 | File/Lines                                                       | Responsibility                                                                           |
+| ---------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Connection Manager** | `main.go` (hub, clients map)                                     | Track active WebSocket connections per room, fan-out messages                            |
+| **Message Parser**     | `main.go` (readPump, handleMessage)                              | Parse JSON envelope `{type, room?, ...}`, validate fields, route to handler              |
+| **Room Registry**      | `main.go` (rooms map, room broadcasts)                           | Map room name → client set, handle join/leave/close                                      |
+| **DM Router**          | `main.go` (handleDirectMessage)                                  | Resolve target user in clients map, deliver private message                              |
+| **Persistence Layer**  | `main.go` (GORM models: Message, DirectMessage, ModerationLog)   | Store/retrieve chat messages, DMs, moderation events                                     |
+| **Redis Subsystem**    | `main.go` (redisClient, rate limiting, pub/sub, presence)        | INCR+EXPIRE rate limit, SETEX presence, PSUBSCRIBE room fan-out                          |
+| **Auth Handler**       | `main.go` (handleAdminLogin, adminAuthMiddleware)                | Session cookie creation/validation, login rate limiting                                  |
+| **User Auth Handler**  | `handlers/handlers.go` (HandleUserRegister/Login/Session/Logout) | Viewer register/login/logout/session (bcrypt, user session cookie)                       |
+| **DM History/Search**  | `handlers/handlers.go` (HandleUserDMHistory, HandleUserDMSearch) | Paginated DM history + search for authenticated users                                    |
+| **Runtime Config**     | `config/runtime.go` (GetRuntime, SetRuntime, typed setters)      | Thread-safe JSON runtime config (HLS duration/window, Matomo)                            |
+| **Admin API Router**   | `main.go` (handleAdmin\*)                                        | Upload, playlist CRUD, schedule overrides, moderation actions, analytics, system summary |
+| **Metrics Exporter**   | `main.go` (prometheus.MustRegister)                              | Expose connected_clients, messages_total, dms_total, moderation_actions, redis_up        |
 
 #### Playout Service Modules
 
-| Module               | File/Lines                                     | Responsibility                                                     |
-| -------------------- | ---------------------------------------------- | ------------------------------------------------------------------ |
-| **Playlist Parser**  | `playlist.go` (parsePlaylist)                  | Read `playlist.txt`, skip comments/blank lines, resolve file paths |
-| **FFmpeg Manager**   | `playlist.go` (runPlayout, restart logic)      | Spawn/monitor FFmpeg concat process, restart on crash              |
-| **Slate Controller** | `playlist.go` (activateSlate, deactivateSlate) | Switch output to slate loop on excessive failures                  |
-| **R2 Sync**          | `playlist.go` (syncToR2)                       | Upload HLS segments + manifest to R2 bucket                        |
-| **Health Endpoint**  | `playlist.go` (healthHandler)                  | `/health` → JSON with mode, segment count, uptime                  |
-| **Metrics Exporter** | `playlist.go` (prometheus)                     | Expose restarts_total, mode (live/slate)                           |
+| Module               | File/Lines                                              | Responsibility                                                                                        |
+| -------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **Playlist Parser**  | `playlist.go` (parsePlaylist)                           | Read `playlist.txt`, skip comments/blank lines, resolve file paths                                    |
+| **FFmpeg Manager**   | `playlist.go` (runPlayout, restart logic)               | Spawn/monitor FFmpeg concat process, restart on crash                                                 |
+| **Loop Controller**  | `playlist.go` (playlistFingerprint, hlsNextStartNumber) | Detect playlist changes (SHA-256), continue segment numbering on clean loops                          |
+| **Slate Controller** | `playlist.go` (activateSlate, deactivateSlate)          | Switch output to slate loop on excessive failures                                                     |
+| **R2 Sync**          | `playlist.go` (syncToR2)                                | Upload HLS segments + manifest to R2 bucket                                                           |
+| **R2 Cleanup**       | `playlist.go` (cleanupOldRuns)                          | Keep the last N run folders under the size cap; delete older `hls/r-*/*` objects                      |
+| **Health Endpoint**  | `playlist.go` (healthHandler)                           | `/health` → JSON with mode, segment count, uptime                                                     |
+| **Metrics Exporter** | `playlist.go` (prometheus)                              | Expose restarts_total, mode (live/slate), loops_total, run_duration_seconds, r2_cleanup_objects_total |
 
 #### Frontend Modules
 
-| Module                  | File                                            | Responsibility                                                    |
-| ----------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
-| **HLS Player**          | `src/main.ts`                                   | hls.js initialization, attach to video element, error recovery    |
-| **WebSocket Client**    | `src/main.ts`                                   | Connect/disconnect, parse envelope, dispatch to UI handlers       |
-| **Chat UI**             | `src/main.ts`                                   | Message list rendering, room tabs, DM panel, presence dots        |
-| **Schedule Overlay**    | `src/main.ts`                                   | Poll `/api/schedule`, render current/next program                 |
-| **Admin Router**        | `src/admin.ts`                                  | Tab-based navigation, dynamic page loading                        |
-| **Upload Manager**      | `src/admin.ts`                                  | Multipart upload with chunk progress, ffprobe validation feedback |
-| **Playlist Editor**     | `src/admin.ts`                                  | Drag-reorder, add/remove items, save to `/api/admin/playlist`     |
-| **Moderation Panel**    | `src/admin.ts` + `public/admin/moderation.html` | Inline mute/ban, action log viewer                                |
-| **Analytics Dashboard** | `src/admin.ts` + `public/admin/analytics.html`  | Message counts, top rooms, moderation stats                       |
-| **System Config**       | `src/admin.ts` + `public/admin/system.html`     | Service health, config metadata, restart buttons                  |
+| Module                  | File                                            | Responsibility                                                                                 |
+| ----------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| **HLS Player**          | `src/main.ts`                                   | hls.js initialization, attach to video element, error recovery                                 |
+| **WebSocket Client**    | `src/main.ts`                                   | Connect/disconnect, parse envelope, dispatch to UI handlers                                    |
+| **Chat UI**             | `src/main.ts`                                   | Message list rendering, room tabs, DM panel, presence dots, typing indicator, user-list toggle |
+| **DM Search**           | `src/main.ts`                                   | Search DM history (`/api/dm/search`) and render results                                        |
+| **Auth UI**             | `src/main.ts` + `index.html`                    | Viewer login/register/logout, session refresh, user label                                      |
+| **Schedule Overlay**    | `src/main.ts`                                   | Poll `/api/schedule`, render current/next program                                              |
+| **Admin Router**        | `src/admin.ts`                                  | Tab-based navigation, dynamic page loading                                                     |
+| **Upload Manager**      | `src/admin.ts`                                  | Multipart upload with chunk progress, normalization status badges                              |
+| **Playlist Editor**     | `src/admin.ts`                                  | Drag-reorder, add/remove items (gated to `ready` media), save to `/api/admin/playlist`         |
+| **Moderation Panel**    | `src/admin.ts` + `public/admin/moderation.html` | Inline mute/ban, action log viewer                                                             |
+| **Analytics Dashboard** | `src/admin.ts` + `public/admin/analytics.html`  | Message counts, top rooms, moderation stats                                                    |
+| **System Config**       | `src/admin.ts` + `public/admin/system.html`     | Service health, runtime config form (HLS duration/window, Matomo), restart buttons             |
 
 ## Runtime View
 
 ### Playout & Delivery Scenario
 
 1. Admin adds normalized MP4 to R2 + updates playlist.
-2. Playout worker (FFmpeg loop with concat demuxer) reads next file, packages as HLS segments (4-6s).
+2. Playout worker (FFmpeg loop with concat demuxer) reads next file, packages as HLS segments (2s).
 3. Segments uploaded to R2 with unique immutable names; live `.m3u8` updated.
 4. Viewer loads SPA → requests master/live manifest → hls.js player follows current edge.
 5. Cloudflare serves `.m4s` and `.ts` from nearest edge cache (origin/R2 hit only once per POP/region).
@@ -452,7 +461,7 @@ flowchart LR
 
 ### Infrastructure Level 1
 
-**Overview Diagram**: See Mermaid in Building Block section (VPS + Cloudflare R2/Pages/CDN).
+**Overview Diagram**: See Mermaid in Building Block section (VPS + Cloudflare R2/Workers/CDN).
 
 **Motivation**: Low-cost US-East origin with global edge caching. Hetzner provides excellent price/performance and included traffic; Cloudflare eliminates egress fees.
 
@@ -461,7 +470,7 @@ flowchart LR
 **Mapping of Building Blocks to Infrastructure**:
 
 - Playout + Chat + Nginx → Hetzner Cloud CX22 (Ashburn, VA).
-- HLS storage, caching, static SPA → Cloudflare R2 + CDN + Pages (custom domains, `enam` location hint).
+- HLS storage, caching, static SPA → Cloudflare R2 + CDN + Workers (custom domains, `enam` location hint).
 - All public traffic routed through Cloudflare.
 
 ### Infrastructure Level 2
@@ -473,7 +482,7 @@ flowchart LR
 - R2 bucket for media.
 - Cache Rules (`.m4s` and `.ts`: Cache Everything, immutable, long TTL; `.m3u8`: short TTL/must-revalidate).
 - WAF, rate limiting, Tiered Cache.
-- Pages for SPA hosting.
+- Workers for SPA hosting.
 
 Future evolution: Docker Compose, managed DB, secondary regions (detailed in subsequent ADRs).
 
@@ -485,7 +494,7 @@ Immutable segment naming + targeted Cloudflare Cache Rules + R2 ($0 egress) = ne
 
 ### Video Normalization & Playout
 
-All source assets must be pre-normalized before they are accepted into production playlists. This prevents decode resets, timestamp drift, and audio/video discontinuities during continuous concat playout.
+All source assets must conform to the Linear Void source profile before they are accepted into production playlists. The chat backend **auto-normalizes** non-conforming uploads on ingest (`media.NormalizeVideo`), so admins no longer need to pre-process files manually. This prevents decode resets, timestamp drift, and audio/video discontinuities during continuous concat playout.
 
 #### Required Source Profile (Linear Void v1)
 
@@ -513,12 +522,27 @@ ffmpeg -i input.mov \
   output-normalized.mp4
 ```
 
-#### Verification Gate (ffprobe)
+#### Automatic Normalization & Verification (ffprobe)
 
-- Validate codec, fps, resolution, and keyframe cadence before upload acceptance.
-- Reject non-conforming files from admin ingest with actionable error feedback.
+- `media.NormalizeVideo` runs ffmpeg with the Linear Void profile (H.264/AAC, 30fps, 2s keyframes, yuv420p, 48kHz stereo), writes `*.normalized.mp4`, and re-verifies the output with ffprobe.
+- Media records carry a status: `ready`, `needs_normalization`, `normalizing`, or `normalization_failed`; the admin UI shows a "Normalize" action with status polling.
+- `POST /api/admin/media/{id}/normalize` re-triggers normalization manually for failed/re-queued media.
 - Keep verification logic aligned with runtime playout assumptions to preserve `-c copy` efficiency where possible.
 
+### Runtime Configuration Store
+
+A thread-safe, JSON-persisted runtime config store lives in `backend/chat/src/config/runtime.go` and is shared with the playout service via the playlist volume (`/app/playlist/config.json`).
+
+- Editable via `GET/PUT /api/admin/config` from the admin UI.
+- Fields: `hlsSegmentDuration` (2–15s, default 2), `hlsWindowSize` (3–100, default 12), `matomoUrl`, `matomoSiteId`.
+- Playout reads the same file (`loadSharedHLSConfig`) as an env fallback for HLS segment duration/window.
+- Typed setters validate values; invalid input is rejected with `400`.
+
+### Analytics (Matomo)
+
+- The viewer sends pageviews to Matomo driven by the public `GET /api/matomo` endpoint, which returns `matomoUrl` + `matomoSiteId` from the runtime config store.
+- Analytics is optional per deployment: leave `matomoUrl` empty to disable tracking.
+
 ### Monitoring & Resilience
 
 Linear Void uses a two-layer monitoring model:
@@ -538,6 +562,7 @@ Linear Void uses a two-layer monitoring model:
   - `postgres` -> `postgres-exporter:9187`
   - `node` -> `node-exporter:9100`
   - `prometheus` -> `localhost:9090`
+- TSDB retention: `--storage.tsdb.retention.time=30d` (delete metrics older than 30 days) + `--storage.tsdb.retention.size=15GB` (disk cap), set on the `prometheus` service in `docker-compose.yml` and `docker-compose.prod.yml`
 
 #### Grafana Dashboards
 
@@ -550,7 +575,7 @@ Use the app dashboard for service-level behavior and the Prometheus overview das
 
 Rules are implemented in `monitoring/prometheus/alerts.yml` and loaded via `rule_files` from `prometheus.yml`.
 
-Current rule set (8):
+Current rule set (10):
 
 - `ChatDown`
 - `PlayoutDown`
@@ -559,6 +584,8 @@ Current rule set (8):
 - `HighChatLatency`
 - `PrometheusWALFailing`
 - `HighCPU`
+- `LowCacheHitRatio`
+- `HighRedisMemoryUsage`
 - `LowDiskSpace`
 
 Route warning/critical severities to the operations channel and keep runbook links attached to each alert definition.
@@ -611,6 +638,8 @@ Linear Void currently exposes three operational API surfaces. The canonical deta
   - `/api/admin/session`
 - Operational/admin domains:
   - overview, analytics, users, moderation, schedule, playlist, media
+  - runtime config: `GET/PUT /api/admin/config` (HLS segment duration/window, Matomo)
+  - media normalization: `POST /api/admin/media/{id}/normalize`
 - Media upload domain:
   - `/api/admin/media/uploads` (init/resume)
   - `/api/admin/media/uploads/{uploadId}/chunk`
@@ -620,6 +649,19 @@ Linear Void currently exposes three operational API surfaces. The canonical deta
   - media metadata + upload orchestration
   - moderation/audit and system status management
 
+#### Viewer REST API
+
+- Auth/session:
+  - `POST /api/auth/register`
+  - `POST /api/auth/login`
+  - `POST /api/auth/logout`
+  - `GET /api/auth/session`
+- Private messaging:
+  - `GET /api/dm/history` (paginated)
+  - `GET /api/dm/search`
+- Analytics:
+  - `GET /api/matomo` (public; returns Matomo URL + site ID for the viewer pageview snippet)
+
 ### Cloudflare Configuration Reference
 
 Cloudflare is part of the production control plane, not only a CDN edge. The following configuration set is required to maintain cost, latency, and reliability targets.
@@ -669,7 +711,7 @@ Security is split between edge controls (Cloudflare), reverse proxy controls (ng
 #### Transport and Edge Protection
 
 - Public traffic uses HTTPS/WSS at the edge.
-- Cloudflare WAF and rate limiting are part of the baseline (see `infrastructure/cloudflare/cache-rules.md`).
+- Cloudflare WAF and rate limiting are part of the baseline (see [cache-rules](../docs/infrastructure/cloudflare/cache-rules.md)).
 - Cloudflare Worker can enforce immutable cache headers for segment paths (`infrastructure/cloudflare/worker.js`).
 
 #### Reverse Proxy Enforcement (nginx)
@@ -685,6 +727,12 @@ Security is split between edge controls (Cloudflare), reverse proxy controls (ng
 - Session cookie controls in backend include `HttpOnly`, `SameSite=Strict`, and `Secure` when request is HTTPS (derived from TLS or `X-Forwarded-Proto`).
 - Session expiration is enforced server-side.
 
+#### Viewer User Accounts
+
+- Register/login/logout via `POST /api/auth/register`, `POST /api/auth/login`, `POST /api/auth/logout`; current session via `GET /api/auth/session`.
+- Passwords are hashed with bcrypt; sessions use a `linearvoid_user_session` cookie with a 30-day default TTL (`USER_SESSION_TTL_HOURS`).
+- Viewer sign-in UI (username/password) lives in `frontend/index.html`.
+
 #### Rate Limiting and Abuse Controls
 
 - Chat message rate limiting uses Redis `INCR + EXPIRE` windowing.
@@ -706,6 +754,9 @@ Security is split between edge controls (Cloudflare), reverse proxy controls (ng
 
 WebSockets + Redis (presence, pub/sub, rate limits) + DB (history, audit). Public rooms + on-demand private chats. Scales independently of video.
 
+- Private DM history (`GET /api/dm/history`, paginated) and search (`GET /api/dm/search`) are backed by persisted DMs.
+- Viewer UI includes a typing indicator, user-list toggle, and DM search.
+
 Full details, cache rule table, bitrate/storage calculations, cost model, example configs, ToS notes, and implementation phases are in [`adr/ADR-001.md`](adr/ADR-001.md).
 
 ## Architecture Decisions
@@ -727,7 +778,7 @@ These ADRs together form the canonical decision log.
 - Self-managed US-East playout (Hetzner Ashburn) with FFmpeg + MediaMTX/SRS → HLS → Cloudflare R2 + edge caching.
 - Module structure that directly reflects the arc42 building blocks and context diagram.
 - Go preferred for performance-critical services; TypeScript for frontend; Docker for all deployment.
-- Admin interfaces for video management, moderation, analytics, and system configuration using HTMX + Tailwind.
+- Admin interfaces for video management, moderation, analytics, and system configuration using HTMX + custom CSS.
 - SQLite as primary database for v1 with PostgreSQL migration path if needed.
 - Redis for rate limiting, presence, pub/sub, session storage with defined TTL policies and fallback behavior.
 

docs/architecture/adr/ADR-001.md

@@ -69,7 +69,7 @@ Adopt a **self-managed US-East playout + Cloudflare R2 + edge-cached HLS** archi
 
 ### 3. Frontend
 
-- Static SPA (HTML/CSS/JS + Tailwind + Alpine.js or vanilla) hosted on Cloudflare Pages or same VPS/Nginx.
+- Static SPA (HTML + custom CSS + vanilla JS) hosted on Cloudflare Workers or same VPS/Nginx.
 - Video player: `hls.js` (Chromium/Firefox) or native HLS (Safari). Single live `master.m3u8`.
 - Embedded chat sidebar with room switcher, private DMs, now-playing overlay.
 
@@ -82,7 +82,7 @@ Adopt a **self-managed US-East playout + Cloudflare R2 + edge-cached HLS** archi
 
 ### 5. Infrastructure Summary & Cost Model
 
-- **Primary**: Hetzner Ashburn VPS (playout + chat + Nginx) + Cloudflare R2 + Pages.
+- **Primary**: Hetzner Ashburn VPS (playout + chat + Nginx) + Cloudflare R2 + Workers.
 - **Monitoring**: MediaMTX/SRS dashboard, UptimeRobot, systemd logs, Cloudflare analytics.
 - **Backup**: Weekly R2/S3-compatible snapshots of playlist, DB, config.
 - **Fallback**: Emergency slate/loop playlist, automated restart.

docs/architecture/adr/ADR-003-tech-stack.md

@@ -25,7 +25,7 @@ We must explicitly document language/runtime choices per module and the assumpti
 
 | Layer               | Technology                                 | Language                | Rationale                                                                                                              |
 | ------------------- | ------------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Frontend SPA**    | HTML + Tailwind + Alpine.js + hls.js       | TypeScript / JavaScript | Minimal bundle, excellent HLS support, fast iteration. Vite for build.                                                 |
+| **Frontend SPA**    | HTML + custom CSS + vanilla JS + hls.js    | TypeScript / JavaScript | Minimal bundle, excellent HLS support, fast iteration. Vite for build.                                                 |
 | **Playout Service** | FFmpeg + MediaMTX (or SRS)                 | Bash + Go (wrapper)     | FFmpeg is the proven tool for continuous playlist HLS. Go wrapper for reliability and monitoring.                      |
 | **Chat Backend**    | Go (preferred) or Node.js + Socket.io      | Go                      | High-performance WebSockets, low memory, excellent Redis/PostgreSQL clients. Node.js acceptable for rapid prototyping. |
 | **Shared Code**     | TypeScript definitions + Go structs        | TS + Go                 | Clear contracts between frontend and backend.                                                                          |
@@ -38,7 +38,7 @@ We must explicitly document language/runtime choices per module and the assumpti
 
 1. All video assets **must** be normalized before being added to any playlist (H.264, AAC, 30 fps constant, 2s keyframes, CRF encoding).
 2. Deployment is **Docker-first**; services will be containerized.
-3. Cloudflare is the primary CDN and will be configured with specific [Cache Rules](../../../infrastructure/cloudflare/cache-rules.md).
+3. Cloudflare is the primary CDN and will be configured with specific [Cache Rules](../../infrastructure/cloudflare/cache-rules.md) for HLS segments and manifests.
 4. Chat does **not** require end-to-end encryption in v1 (separate ADR if needed).
 5. Single VPS origin initially; multi-region is a later evolution.
 6. Monitoring focuses on playout health, cache hit ratio, and R2 operation counts.

docs/architecture/adr/ADR-004-admin-video.md

@@ -19,7 +19,7 @@ This interface must be lightweight, secure, and integrated with the playout serv
 
 ## Decision Drivers
 
-1. **Lightweight & Maintainable** – Prefer server-rendered or minimal JS (HTMX + Tailwind) over heavy SPA frameworks to align with ADR-003's "lightweight" principle.
+1. **Lightweight & Maintainable** – Prefer server-rendered or minimal JS (HTMX + custom CSS) over heavy SPA frameworks to align with ADR-003's "lightweight" principle.
 2. **Security** – Strict authentication, file type/size validation, and R2 upload permissions.
 3. **Usability** – Drag-and-drop playlist editor, progress indicators for normalization and upload, real-time playout status.
 4. **Integration** – Must call playout service APIs for validation and playlist updates; upload directly to R2 with metadata.
@@ -31,7 +31,7 @@ Create a dedicated **admin web interface** in a new `frontend/admin/` directory
 
 **Tech Stack (per ADR-003)**:
 
-- **Frontend**: HTMX + Tailwind CSS + Alpine.js (minimal JS, server-rendered HTML). Alternative: React if complex interactions are needed later.
+- **Frontend**: HTMX + custom CSS + minimal JS (server-rendered HTML). Alternative: React if complex interactions are needed later.
 - **Backend**: Go (or Node.js) API endpoints exposed by the playout service or a dedicated `backend/admin/` service.
 - **Authentication**: JWT or session-based (admin roles only). Use Cloudflare Access or simple OAuth for production.
 - **File Handling**: Upload → validate with ffprobe (codec, fps, keyframes, duration) → normalize if needed → store in R2 with metadata.
@@ -48,7 +48,7 @@ Create a dedicated **admin web interface** in a new `frontend/admin/` directory
 
 **Folder Placement** (per ADR-002):
 
-- `frontend/admin/` – Admin-specific HTML/JS components (HTMX + Tailwind).
+- `frontend/admin/` – Admin-specific HTML/JS components (HTMX + custom CSS).
 - `backend/admin/` – Dedicated API handlers for validation, playlist updates, and configuration (or extend playout/chat services).
 - Protected route in nginx with authentication (JWT or Cloudflare Access).
 - Documentation and API specs added to `docs/architecture/`.
@@ -95,7 +95,7 @@ Create a dedicated **admin web interface** in a new `frontend/admin/` directory
 
 - ADR-001: Normalization requirements, HLS playout, R2 usage.
 - ADR-002: Folder structure (admin UI belongs under frontend or a protected route).
-- ADR-003: Lightweight frontend preference (HTMX/Tailwind over heavy frameworks).
+- ADR-003: Lightweight frontend preference (HTMX/custom CSS over heavy frameworks).
 - arc42 documentation: Building Block View (admin as part of the overall system).
 
 This ADR ensures all admin interface decisions are documented before code is written.

docs/architecture/adr/ADR-005-admin-moderation-analytics.md

@@ -17,7 +17,7 @@ These interfaces must be secure, auditable, and integrated with the chat backend
 
 ## Decision Drivers
 
-1. **Consistency** – Use the same lightweight tech stack decided in ADR-004 (HTMX + Tailwind + Alpine.js) to avoid introducing new frameworks.
+1. **Consistency** – Use the same lightweight tech stack decided in ADR-004 (HTMX + custom CSS + vanilla JS) to avoid introducing new frameworks.
 2. **Security & Auditability** – All actions must require admin authentication and be logged immutably.
 3. **Real-time Needs** – Moderation dashboard should show live chat activity (WebSocket integration).
 4. **Simplicity** – Analytics should use existing Prometheus/Grafana data where possible rather than building a duplicate system.
@@ -29,7 +29,7 @@ Extend the admin interface started in ADR-004 with additional protected sections
 
 **Tech Stack (consistent with ADR-003 and ADR-004)**:
 
-- **Frontend**: HTMX + Tailwind + Alpine.js for all admin pages. Shared layout with sidebar navigation.
+- **Frontend**: HTMX + custom CSS + vanilla JS for all admin pages. Shared layout with sidebar navigation.
 - **Backend**: Go API endpoints (protected by JWT/session middleware) in `backend/admin/` or extended from the chat/playout services.
 - **Authentication**: Role-based (admin, moderator, viewer). Use Cloudflare Access or JWT with short expiry for production.
 - **Data Sources**:
@@ -54,7 +54,7 @@ Extend the admin interface started in ADR-004 with additional protected sections
 
 ## Rationale
 
-- Reusing HTMX/Tailwind from ADR-004 keeps the admin interface lightweight and consistent.
+- Reusing HTMX/custom CSS from ADR-004 keeps the admin interface lightweight and consistent.
 - Centralizing admin functionality under `/admin/` reduces maintenance overhead.
 - Leveraging Prometheus/Grafana for analytics avoids duplicating metrics collection.
 - Immutable audit logging supports future compliance and moderation review (key requirement for a public chat system).
@@ -94,7 +94,7 @@ Extend the admin interface started in ADR-004 with additional protected sections
 
 - ADR-001: Chat features, moderation requirements, monitoring needs.
 - ADR-002: Folder structure – admin UI belongs under `frontend/admin/`.
-- ADR-003: Lightweight frontend (HTMX/Tailwind) and Go backend preference.
+- ADR-003: Lightweight frontend (HTMX/custom CSS) and Go backend preference.
 - ADR-004: Video admin interface (shared layout and authentication approach).
 - arc42 documentation: Cross-cutting Concepts (security, monitoring) and Building Block View (admin as extension of the system).
 

docs/infrastructure/cloudflare/cloudflare-account-troubleshooting.md

@@ -0,0 +1,24 @@
+# Cloudflare Account Troubleshooting
+
+Reference for Cloudflare account and API token troubleshooting.
+
+Use `wrangler whoami` to verify the account ID and API token are valid, or query the Workers API at `https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/workers/scripts`.
+
+## Validate Cloudflare account and API token
+
+```powershell
+# Validate Cloudflare account and API token in .env
+Set-Location -Path "E:\Documents\02-Projects\07-Mentoring\Corey\linearvoid"
+Get-Content .env | Select-String 'CLOUDFLARE_API_TOKEN'
+Get-Content .env | Select-String 'CLOUDFLARE_ACCOUNT_ID'
+
+# Test API token with wrangler
+npx wrangler whoami
+
+# Or verify with the Workers API directly
+$env:CLOUDFLARE_API_TOKEN = (Get-Content .env | Select-String 'CLOUDFLARE_API_TOKEN' | ForEach-Object { $_.Line.Split('=')[1].Trim() })
+$env:CLOUDFLARE_ACCOUNT_ID = (Get-Content .env | Select-String 'CLOUDFLARE_ACCOUNT_ID' | ForEach-Object { $_.Line.Split('=')[1].Trim() })
+
+# List all Workers for the account
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$env:CLOUDFLARE_ACCOUNT_ID/workers/scripts" -H "Authorization: Bearer $env:CLOUDFLARE_API_TOKEN" -H "Content-Type: application/json"
+```

docs/infrastructure/monitoring/prometheus_curl.md

@@ -0,0 +1,62 @@
+# Prometheus scrape target metric names
+
+Here are ready‑to‑run **cURL** commands you can use to query each Prometheus scrape target and list the metric names they expose.  
+The Prometheus HTTP API endpoint `http://localhost:9090/api/v1/label/__name__/values` returns all metric names currently known for the target’s job/instance.
+
+## 1. Chat (`http://chat:3000/metrics`)
+
+[Browse `chat`](http://192.168.88.40:9090/api/v1/label/__name__/values?match[]={job=%22chat%22})
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="chat",instance="chat:3000"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#chat-metrics) for full output of all 20+ metric names exposed by the Chat service.
+
+## 2. NGINX exporter (`http://nginx-exporter:9113/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="nginx",instance="nginx-exporter:9113"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#nginx-metrics) for full output of all 40+ metric names exposed by the NGINX exporter.
+
+## 3. Node exporter (`http://node-exporter:9100/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="node",instance="node-exporter:9100"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#node-metrics) for full output of all 200+ metric names exposed by the Node exporter.
+
+## 4. Playout (`http://playout:8081/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="playout",instance="playout:8081"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#playout-metrics) for full output of all 10+ metric names exposed by the Playout service.
+
+## 5. Postgres exporter (`http://postgres-exporter:9187/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="postgres",instance="postgres-exporter:9187"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#postgres-metrics) for full output of all 100+ metric names exposed by the Postgres exporter.
+
+## 6. Prometheus itself (`http://prometheus:9090/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="prometheus",instance="prometheus:9090"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#prometheus-metrics) for full output of all 100+ metric names exposed by Prometheus itself.
+
+## 7. Redis exporter (`http://redis-exporter:9121/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="redis",instance="redis-exporter:9121"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#redis-metrics) for full output of all 100+ metric names exposed by the Redis exporter.

docs/operations/cloudflare-uptimerobot-checklist.md

@@ -5,7 +5,7 @@ Purpose: execute and record all manual dashboard tasks that cannot be automated
 Recommended execution order:
 
 1. Bind `media.linearvoid.tv` and confirm the HLS origin is separate from the app origin.
-2. Enable Pages, Tiered Cache, and cache behavior for the media zone.
+2. Enable Workers, Tiered Cache, and cache behavior for the media zone.
 3. Apply WAF, bot, rate limiting, HTTPS, and HSTS settings.
 4. Verify monitor targets and alert delivery in UptimeRobot.
 5. Capture evidence and fill in the sign-off block.
@@ -15,18 +15,18 @@ Recommended execution order:
 - [ ] Pending
 - [x] Done
 
-## 1) Cloudflare Pages Link and Build
+## 1) Cloudflare Workers Deploy and Custom Domain
 
-- [ ] Connect repo to Cloudflare Pages project
+- [ ] Create a Cloudflare Worker for the SPA and bind the build output
 - [ ] Build command set to: `cd frontend && npm run build`
 - [ ] Output directory set to: `frontend/dist`
 - [ ] Production domain attached to `linearvoid.tv`
 
 Evidence to capture:
 
-- Screenshot of Pages deployment settings
+- Screenshot of Worker deployment settings
 - Deployment URL and latest deployment timestamp
-- Confirmed production build output path in the Pages project
+- Confirmed production build output path in the Worker
 
 ## 2) Tiered Cache Enablement and Validation
 
@@ -125,7 +125,7 @@ Evidence to capture:
 
 Completion summary:
 
-- Pages build URL:
+- Worker build URL:
 - Cache validation result:
 - WAF/rate-limit status:
 - HTTPS/HSTS status:

docs/operations/cloudflare-workers-setup.md

@@ -0,0 +1,66 @@
+# Cloudflare Workers Setup — Linear Void
+
+Linear Void uses Cloudflare Workers for two purposes:
+
+| Product     | Purpose            | What                                                                                 |
+| ----------- | ------------------ | ------------------------------------------------------------------------------------ |
+| **Workers** | Static SPA hosting | Vite-built frontend (`frontend/dist`) served as Worker static assets                 |
+| **Workers** | Edge cache logic   | `infrastructure/cloudflare/worker.js` — adds immutable cache headers to HLS segments |
+
+Both are managed under **Workers & Pages** in the Cloudflare dashboard.
+
+## Dashboard URLs
+
+| Resource                 | URL                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| Workers & Pages overview | `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers-and-pages`                                    |
+| Worker: linearvoid       | `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers/services/view/linearvoid/production/settings` |
+| API tokens               | <https://dash.cloudflare.com/profile/api-tokens>                                                                    |
+
+## Worker: `linearvoid` (edge cache headers)
+
+The Worker at `infrastructure/cloudflare/worker.js` runs on the `linearvoid` Workers service. It intercepts requests and adds immutable `Cache-Control` headers to `.m4s` segment files.
+
+Deploy via Wrangler CLI:
+
+```bash
+npx wrangler deploy infrastructure/cloudflare/worker.js
+```
+
+Or paste into the Workers dashboard at the URL above (Quick Edit).
+
+## Worker: static frontend
+
+Serve the Vite-built SPA (`frontend/dist`) as Worker static assets:
+
+1. Build the frontend: `cd frontend && npm run build`.
+2. Bind `frontend/dist` to the Worker as static assets (Workers Static Assets / `assets` in `wrangler.toml`).
+3. Attach the `linearvoid.tv` custom domain to the Worker.
+
+See [gitea-cloudflare-workers.md](./gitea-cloudflare-workers.md) for the automated deployment workflow.
+
+### Build-time variables
+
+The `VITE_PUBLIC_*` values are baked into the bundle at build time by Vite (`vite.config.ts` uses `envDir: ".."` to read them from the repo root). They are supplied by the Gitea Actions build environment from Gitea secrets — not as Worker runtime variables. The static-assets Worker has no runtime JavaScript, so it reads no `env` at request time.
+
+| Name                                     | Value                                           |
+| ---------------------------------------- | ----------------------------------------------- |
+| `VITE_PUBLIC_APP_URL`                    | `https://linearvoid.tv`                         |
+| `VITE_PUBLIC_WS_URL`                     | `wss://linearvoid.tv/ws`                        |
+| `VITE_PUBLIC_HLS_URL`                    | `https://media.linearvoid.tv/hls/playlist.m3u8` |
+| `VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR`    | `boogers`                                       |
+| `VITE_PUBLIC_ADMIN_DEFAULT_ROOM`         | `main`                                          |
+| `VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT` | `50`                                            |
+
+Backend services (playout, chat, nginx) read their own runtime variables (`ADMIN_*`, `HLS_*`, `PLAYLIST_PATH`, `R2_*`, `DATABASE_URL`, `REDIS_URL`) from the container environment — see [`.env.example`](../../.env.example).
+
+## Custom domains
+
+- `linearvoid.tv` → Worker (static SPA)
+- `www.linearvoid.tv` → redirect to `linearvoid.tv`
+- `media.linearvoid.tv` → R2 bucket (separate; not a Worker)
+
+## Related
+
+- [Gitea to Cloudflare Workers deployment guide](./gitea-cloudflare-workers.md)
+- [Cloudflare & UptimeRobot checklist](./cloudflare-uptimerobot-checklist.md)

docs/operations/gitea-cloudflare-workers.md

@@ -0,0 +1,107 @@
+# Gitea to Cloudflare Workers — Linear Void
+
+## Goal
+
+Deploy the Linear Void frontend (Vite + TypeScript SPA) from Gitea to Cloudflare Workers using Gitea Actions and Wrangler.
+
+## Prerequisites
+
+1. **Cloudflare Worker** for the SPA:
+   - Dashboard → Workers & Pages → Create → Worker (or Workers Static Assets).
+   - Name it `linearvoid-frontend` (the edge-cache Worker already uses the `linearvoid` name).
+2. **API token** with Workers permissions:
+   - Create at <https://dash.cloudflare.com/profile/api-tokens>
+   - Permission: `Account → Workers Scripts → Edit` and `Account → Workers Routes → Edit`
+   - Store in Gitea → Settings → Secrets as `CLOUDFLARE_API_TOKEN`
+3. **Account ID** from Cloudflare dashboard overview → store as `CLOUDFLARE_ACCOUNT_ID`
+4. **Wrangler config** (`frontend/wrangler.toml`) binding the `frontend/dist` output as static assets.
+
+> **Naming conflict:** Workers share a namespace under "Workers & Pages". The edge-cache Worker (`infrastructure/cloudflare/worker.js`) already uses the `linearvoid` name, so the SPA Worker is named `linearvoid-frontend` (see `frontend/wrangler.toml`).
+
+## Project-specific values
+
+| Setting            | Value                                                      |
+| ------------------ | ---------------------------------------------------------- |
+| Framework          | Vite + TypeScript                                          |
+| Build command      | `cd frontend && npm install && npm run build`              |
+| Output directory   | `frontend/dist`                                            |
+| Node version       | 22                                                         |
+| Multi-page entries | `index.html`, `admin/index.html`, `admin/login/index.html` |
+
+## Gitea Actions workflow
+
+Build the SPA and deploy with Wrangler:
+
+```yaml
+name: Deploy to Cloudflare Workers
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+  workflow_dispatch: {}
+
+jobs:
+  deploy:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: cd frontend && npm ci
+
+      - name: Build
+        env:
+          VITE_PUBLIC_APP_URL: ${{ secrets.VITE_PUBLIC_APP_URL }}
+          VITE_PUBLIC_WS_URL: ${{ secrets.VITE_PUBLIC_WS_URL }}
+          VITE_PUBLIC_HLS_URL: ${{ secrets.VITE_PUBLIC_HLS_URL }}
+          VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR: ${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR }}
+          VITE_PUBLIC_ADMIN_DEFAULT_ROOM: ${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_ROOM }}
+          VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT: "50"
+        run: cd frontend && npm run build
+
+      - name: Deploy to Cloudflare Workers
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          cd frontend
+          npx wrangler deploy
+```
+
+## Secrets to add in Gitea
+
+| Secret                                | Value                                |
+| ------------------------------------- | ------------------------------------ |
+| `CLOUDFLARE_API_TOKEN`                | API token with Workers permissions   |
+| `CLOUDFLARE_ACCOUNT_ID`               | Cloudflare account ID from dashboard |
+| `VITE_PUBLIC_APP_URL`                 | Public viewer URL                    |
+| `VITE_PUBLIC_WS_URL`                  | WebSocket endpoint                   |
+| `VITE_PUBLIC_HLS_URL`                 | HLS playlist URL                     |
+| `VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR` | Default moderator username           |
+| `VITE_PUBLIC_ADMIN_DEFAULT_ROOM`      | Default chat room                    |
+
+## Verify deployment
+
+1. Push to `main` or trigger manually from Gitea Actions.
+2. Check **Gitea Actions** → job logs for the deploy step.
+3. Check **Cloudflare Workers** → `linearvoid-frontend` → Deployments for the new version.
+4. Visit `https://linearvoid-frontend.zwitschi82.workers.dev`, then attach `linearvoid.tv` when ready.
+
+## Notes
+
+- The existing `ci.yml` already builds the frontend; the Workers deploy workflow is additive and independent.
+- Multi-page SPA (`vite.config.ts`) produces three entry points — Workers static assets serve them correctly.
+- For SPA fallback routing, set Workers static assets `not_found_handling` to `single-page-application` (serve `index.html` for unknown paths).
+- The deploy workflow lives in `.gitea/workflows/workers-deploy.yml` (triggered after CI succeeds).
+
+## Related resources
+
+- Cloudflare Workers dashboard: `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers/services/view/linearvoid/production/settings` — for managing the `infrastructure/cloudflare/worker.js` deployment and the SPA Worker

frontend/admin/index.html

@@ -1,130 +1,63 @@
 <!doctype html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Linear Void Admin</title>
-    <link rel="stylesheet" href="../src/style.css" />
-  </head>
 
-  <body class="admin-body">
-    <div class="admin-shell">
-      <aside class="admin-sidebar" aria-label="Primary">
-        <div class="brand-block">
-          <div class="brand-badge" aria-hidden="true">LV</div>
-          <div class="brand-text">Admin</div>
-        </div>
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Linear Void Admin</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Doto:wght@100..900&family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&family=Space+Grotesk:wght@300..700&family=Tektur:wght@400..900&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="../src/style.css" />
+</head>
 
-        <button id="logout-btn" type="button" class="btn btn-secondary btn-block">Sign out</button>
+<body class="admin-body">
+  <div class="admin-shell">
+    <aside class="admin-sidebar" aria-label="Primary">
+      <div class="brand-block">
+        <div class="brand-badge" aria-hidden="true">LV</div>
+        <div class="brand-text">Admin</div>
+      </div>
 
-        <nav class="admin-nav" aria-label="Admin sections" role="tablist" aria-orientation="vertical">
-          <button
-            type="button"
-            id="tab-trigger-dashboard"
-            role="tab"
-            class="tab-trigger is-active"
-            data-tab="dashboard"
-            aria-controls="tab-dashboard"
-            aria-selected="true"
-          >
-            Dashboard
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-upload"
-            role="tab"
-            class="tab-trigger"
-            data-tab="upload"
-            aria-controls="tab-upload"
-            aria-selected="false"
-          >
-            Upload Video
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-playlist"
-            role="tab"
-            class="tab-trigger"
-            data-tab="playlist"
-            aria-controls="tab-playlist"
-            aria-selected="false"
-          >
-            Playlist
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-schedule"
-            role="tab"
-            class="tab-trigger"
-            data-tab="schedule"
-            aria-controls="tab-schedule"
-            aria-selected="false"
-          >
-            Schedule
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-moderation"
-            role="tab"
-            class="tab-trigger"
-            data-tab="moderation"
-            aria-controls="tab-moderation"
-            aria-selected="false"
-          >
-            Moderation
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-chat-log"
-            role="tab"
-            class="tab-trigger"
-            data-tab="chat-log"
-            aria-controls="tab-chat-log"
-            aria-selected="false"
-          >
-            Chat Log
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-users"
-            role="tab"
-            class="tab-trigger"
-            data-tab="users"
-            aria-controls="tab-users"
-            aria-selected="false"
-          >
-            Users
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-analytics"
-            role="tab"
-            class="tab-trigger"
-            data-tab="analytics"
-            aria-controls="tab-analytics"
-            aria-selected="false"
-          >
-            Analytics
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-system"
-            role="tab"
-            class="tab-trigger"
-            data-tab="system"
-            aria-controls="tab-system"
-            aria-selected="false"
-          >
-            System
-          </button>
-        </nav>
-      </aside>
+      <button id="logout-btn" type="button" class="btn btn-secondary btn-block">Sign out</button>
 
-      <main class="admin-main" id="admin-main" tabindex="-1">
-        <div id="tab-content-container" aria-live="polite">Loading...</div>
-      </main>
-    </div>
+      <nav class="admin-nav" aria-label="Admin sections" role="tablist" aria-orientation="vertical">
+        <button type="button" id="tab-trigger-dashboard" role="tab" class="tab-trigger is-active" data-tab="dashboard" aria-controls="tab-dashboard" aria-selected="true">
+          Dashboard
+        </button>
+        <button type="button" id="tab-trigger-upload" role="tab" class="tab-trigger" data-tab="upload" aria-controls="tab-upload" aria-selected="false">
+          Upload Video
+        </button>
+        <button type="button" id="tab-trigger-playlist" role="tab" class="tab-trigger" data-tab="playlist" aria-controls="tab-playlist" aria-selected="false">
+          Playlist
+        </button>
+        <button type="button" id="tab-trigger-schedule" role="tab" class="tab-trigger" data-tab="schedule" aria-controls="tab-schedule" aria-selected="false">
+          Schedule
+        </button>
+        <button type="button" id="tab-trigger-moderation" role="tab" class="tab-trigger" data-tab="moderation" aria-controls="tab-moderation" aria-selected="false">
+          Moderation
+        </button>
+        <button type="button" id="tab-trigger-chat-log" role="tab" class="tab-trigger" data-tab="chat-log" aria-controls="tab-chat-log" aria-selected="false">
+          Chat Log
+        </button>
+        <button type="button" id="tab-trigger-users" role="tab" class="tab-trigger" data-tab="users" aria-controls="tab-users" aria-selected="false">
+          Users
+        </button>
+        <button type="button" id="tab-trigger-analytics" role="tab" class="tab-trigger" data-tab="analytics" aria-controls="tab-analytics" aria-selected="false">
+          Analytics
+        </button>
+        <button type="button" id="tab-trigger-system" role="tab" class="tab-trigger" data-tab="system" aria-controls="tab-system" aria-selected="false">
+          System
+        </button>
+      </nav>
+    </aside>
 
-    <script type="module" src="/src/admin.ts"></script>
-  </body>
-</html>
+    <main class="admin-main" id="admin-main" tabindex="-1">
+      <div id="tab-content-container" aria-live="polite">Loading...</div>
+    </main>
+  </div>
+
+  <script type="module" src="/src/admin.ts"></script>
+</body>
+
+</html>

frontend/admin/login/index.html

@@ -1,65 +1,70 @@
 <!doctype html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Linear Void Admin Login</title>
-    <link rel="stylesheet" href="../../src/style.css" />
-  </head>
 
-  <body class="auth-body">
-    <main class="auth-shell" aria-label="Admin authentication">
-      <section class="auth-card" aria-labelledby="auth-title">
-        <p class="auth-kicker">Linear Void</p>
-        <h1 id="auth-title">Admin Login</h1>
-        <p class="auth-subtitle">Authenticate to access protected admin controls.</p>
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Linear Void Admin Login</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Doto:wght@100..900&family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&family=Space+Grotesk:wght@300..700&family=Tektur:wght@400..900&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="../../src/style.css" />
+</head>
 
-        <form id="login-form" class="form-stack" novalidate>
-          <label for="username">Username</label>
-          <input id="username" type="text" class="text-input" autocomplete="username" required />
+<body class="auth-body">
+  <main class="auth-shell" aria-label="Admin authentication">
+    <section class="auth-card" aria-labelledby="auth-title">
+      <p class="auth-kicker">Linear Void</p>
+      <h1 id="auth-title">Admin Login</h1>
+      <p class="auth-subtitle">Authenticate to access protected admin controls.</p>
 
-          <label for="password">Password</label>
-          <input id="password" type="password" class="text-input" autocomplete="current-password" required />
+      <form id="login-form" class="form-stack" novalidate>
+        <label for="username">Username</label>
+        <input id="username" type="text" class="text-input" autocomplete="username" required />
 
-          <button id="submit" type="submit" class="btn btn-primary btn-block">Sign in</button>
-          <p id="status" class="status-line" aria-live="polite"></p>
-        </form>
-      </section>
-    </main>
+        <label for="password">Password</label>
+        <input id="password" type="password" class="text-input" autocomplete="current-password" required />
 
-    <script>
-      const form = document.getElementById("login-form");
-      const username = document.getElementById("username");
-      const password = document.getElementById("password");
-      const submit = document.getElementById("submit");
-      const status = document.getElementById("status");
+        <button id="submit" type="submit" class="btn btn-primary btn-block">Sign in</button>
+        <p id="status" class="status-line" aria-live="polite"></p>
+      </form>
+    </section>
+  </main>
 
-      form.addEventListener("submit", async (event) => {
-        event.preventDefault();
-        submit.disabled = true;
-        status.textContent = "Signing in...";
-        status.className = "status-line";
+  <script>
+    const form = document.getElementById("login-form");
+    const username = document.getElementById("username");
+    const password = document.getElementById("password");
+    const submit = document.getElementById("submit");
+    const status = document.getElementById("status");
 
-        try {
-          const response = await fetch("/api/admin/login", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ username: username.value, password: password.value }),
-          });
+    form.addEventListener("submit", async (event) => {
+      event.preventDefault();
+      submit.disabled = true;
+      status.textContent = "Signing in...";
+      status.className = "status-line";
 
-          if (!response.ok) {
-            throw new Error(`HTTP ${response.status}`);
-          }
+      try {
+        const response = await fetch("/api/admin/login", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ username: username.value, password: password.value }),
+        });
 
-          window.location.href = "/admin/";
-        } catch (error) {
-          console.error("Failed to sign in", error);
-          status.textContent = "Login failed. Check your credentials.";
-          status.className = "status-line status-error";
-        } finally {
-          submit.disabled = false;
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
         }
-      });
-    </script>
-  </body>
-</html>
+
+        window.location.href = "/admin/";
+      } catch (error) {
+        console.error("Failed to sign in", error);
+        status.textContent = "Login failed. Check your credentials.";
+        status.className = "status-line status-error";
+      } finally {
+        submit.disabled = false;
+      }
+    });
+  </script>
+</body>
+
+</html>

frontend/index.html

@@ -1,76 +1,121 @@
 <!doctype html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Linear Void - 24/7 Synchronized Channel</title>
-    <link rel="stylesheet" href="/src/style.css" />
-  </head>
 
-  <body class="lv-body">
-    <main class="viewer-shell" aria-label="Live player and chat">
-      <header class="viewer-header">
-        <div class="viewer-brand-group">
-          <div class="brand-badge" aria-hidden="true">LV</div>
-          <div>
-            <h1 class="viewer-title">Linear Void</h1>
-            <p class="viewer-subtitle">24/7 Synchronized Channel • Live</p>
-          </div>
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Linear Void - 24/7 Synchronized Channel</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Doto:wght@100..900&family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&family=Space+Grotesk:wght@300..700&family=Tektur:wght@400..900&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/src/style.css" />
+</head>
+
+<body class="lv-body">
+  <main class="viewer-shell" aria-label="Live player and chat">
+    <header class="viewer-header">
+      <div class="viewer-brand-group">
+        <div class="brand-badge" aria-hidden="true">LV</div>
+        <div>
+          <h1 class="viewer-title">Linear Void</h1>
+          <p class="viewer-subtitle">24/7 Synchronized Channel • Live</p>
         </div>
-        <button
-          id="chat-toggle"
-          type="button"
-          class="btn btn-secondary chat-toggle-btn"
-          onclick="toggleChatPanel()"
-          aria-controls="chat-panel"
-          aria-expanded="true"
-        >
-          Hide Chat
-        </button>
-      </header>
+      </div>
+      <button id="chat-toggle" type="button" class="btn btn-secondary chat-toggle-btn" onclick="toggleChatPanel()" aria-controls="chat-panel" aria-expanded="true">
+        Hide Chat
+      </button>
+    </header>
 
-      <section class="viewer-content" aria-label="Live stream and chat layout">
-        <section class="player-stage" aria-label="Video stage">
-          <video id="player" class="player" controls autoplay muted playsinline></video>
-          <div id="now-playing" class="now-playing-overlay" aria-live="polite">
-            <span id="np-title">Loading...</span>
-            <span id="np-next" class="np-next"></span>
+    <section class="viewer-content" aria-label="Live stream and chat layout">
+      <section class="player-stage" aria-label="Video stage">
+        <video id="player" class="player" controls autoplay muted playsinline></video>
+        <div id="now-playing" class="now-playing-overlay" aria-live="polite">
+          <span id="np-title">Loading...</span>
+          <span id="np-next" class="np-next"></span>
+        </div>
+      </section>
+
+      <aside id="chat-panel" class="chat-sidebar" aria-label="Chat panel">
+        <header class="chat-header">
+          <div class="chat-room-title">
+            <span class="chat-live-marker" aria-hidden="true">●</span>
+            <span id="room-name">Main Channel</span>
           </div>
+          <div class="chat-header-actions">
+            <span id="chat-user-label" class="chat-user-label" hidden></span>
+            <button id="auth-toggle-btn" type="button" class="btn btn-secondary">Sign in</button>
+            <button id="auth-logout-btn" type="button" class="btn btn-secondary" hidden>Sign out</button> <button id="users-toggle-btn" type="button" class="btn btn-secondary" aria-controls="presence-panel" aria-expanded="true">Users</button> <button type="button" class="btn btn-secondary" onclick="togglePrivateDM()">New DM</button>
+          </div>
+        </header>
+
+        <div id="auth-panel" class="auth-panel" hidden>
+          <input id="auth-username" type="text" class="input" placeholder="Username" autocomplete="username" />
+          <input id="auth-password" type="password" class="input" placeholder="Password" autocomplete="current-password" />
+          <div class="button-row">
+            <button id="auth-login-btn" type="button" class="btn btn-primary">Log in</button>
+            <button id="auth-register-btn" type="button" class="btn btn-secondary">Register</button>
+          </div>
+          <p id="auth-status" class="status-line" aria-live="polite"></p>
+        </div>
+
+        <div id="chat-flash" class="chat-flash" aria-live="polite" hidden></div>
+
+        <section id="messages" class="chat-messages" aria-live="polite"></section>
+
+        <div id="dm-search-row" class="dm-search-row" hidden>
+          <input id="dm-search-input" type="text" class="input" placeholder="Search this conversation..." />
+          <button id="dm-search-btn" type="button" class="btn btn-secondary">Search</button>
+        </div>
+
+        <section id="presence-panel" class="presence-panel">
+          <div id="presence-list" class="presence-list"></div>
         </section>
 
-        <aside id="chat-panel" class="chat-sidebar" aria-label="Chat panel">
-          <header class="chat-header">
-            <div class="chat-room-title">
-              <span class="chat-live-marker" aria-hidden="true">●</span>
-              <span id="room-name">Main Channel</span>
-            </div>
-            <button type="button" class="btn btn-secondary" onclick="togglePrivateDM()">New DM</button>
-          </header>
-
-          <section id="messages" class="chat-messages" aria-live="polite" aria-label="Message stream"></section>
-
-          <section id="presence-panel" class="presence-panel" aria-label="Online users">
-            <div id="presence-list" class="presence-list"></div>
-          </section>
-
-          <div class="chat-input-area">
-            <div class="chat-input-row">
-              <label for="message-input" class="sr-only">Message input</label>
-              <input
-                id="message-input"
-                type="text"
-                placeholder="Type a message..."
-                class="input"
-                onkeydown="if (event.key === 'Enter') sendMessage();"
-              />
-              <button type="button" class="btn btn-primary" onclick="sendMessage()">Send</button>
-            </div>
-            <p class="chat-note">Synced with video • Moderation active</p>
+        <div class="chat-input-area">
+          <div class="chat-input-row">
+            <label for="message-input" class="sr-only">Message input</label>
+            <input id="message-input" type="text" placeholder="Type a message..." class="input" onkeydown="if (event.key === 'Enter') sendMessage();" />
+            <button type="button" class="btn btn-primary" onclick="sendMessage()">Send</button>
           </div>
-        </aside>
-      </section>
-    </main>
+          <p class="chat-note">Synced with video • Moderation active</p>
+        </div>
+      </aside>
+    </section>
+  </main>
 
-    <script type="module" src="/src/main.ts"></script>
-  </body>
-</html>
+  <div id="reconnecting-overlay" class="reconnecting-overlay hidden" role="alert" aria-live="assertive">
+    <div class="reconnecting-spinner"></div>
+    <span id="reconnecting-text">Reconnecting...</span>
+  </div>
+
+  <script>
+    (function () {
+      // Load Matomo analytics when configured via the admin runtime config.
+      fetch("/api/matomo")
+        .then(function (r) {
+          return r.ok ? r.json() : null;
+        })
+        .then(function (cfg) {
+          if (!cfg || !cfg.matomoUrl || !cfg.matomoSiteId) return;
+          var _paq = (window._paq = window._paq || []);
+          _paq.push(["trackPageView"]);
+          _paq.push(["enableLinkTracking"]);
+          var base = String(cfg.matomoUrl).replace(/\/+$/, "");
+          _paq.push(["setTrackerUrl", base + "/matomo.php"]);
+          _paq.push(["setSiteId", String(cfg.matomoSiteId)]);
+          var d = document;
+          var g = d.createElement("script");
+          var s = d.getElementsByTagName("script")[0];
+          g.async = true;
+          g.src = base + "/matomo.js";
+          s.parentNode.insertBefore(g, s);
+        })
+        .catch(function () {
+          /* analytics is optional */
+        });
+    })();
+  </script>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+
+</html>

frontend/package-lock.json

@@ -1,16 +1,17 @@
 {
   "name": "frontend",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frontend",
-      "version": "1.0.9",
+      "version": "1.0.11",
       "dependencies": {
         "hls.js": "^1.6.16"
       },
       "devDependencies": {
+        "@vitest/coverage-v8": "^4.1.10",
         "@vitest/ui": "^4.1.10",
         "jsdom": "^30.0.1",
         "typescript": "~6.0.2",
@@ -51,6 +52,66 @@
         "node": "^22.13.0 || >=24.0.0"
       }
     },
+    "node_modules/@babel/helper-string-parser": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
+      "integrity": "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-identifier": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz",
+      "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/parser": {
+      "version": "7.29.8",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.8.tgz",
+      "integrity": "sha512-E8lTAYNB1KW+FH+VGJuZM1ioAx2E6oVlvQFRrf5P8ZZmsiJXYAD9vTFV7yyEURNzgh1dFqMZuO6tUwcARbqFCA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.29.8"
+      },
+      "bin": {
+        "parser": "bin/babel-parser.js"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@babel/types": {
+      "version": "7.29.8",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.8.tgz",
+      "integrity": "sha512-Vj1jF3cPfxg7OAfoI7QnVKLoILlm2JF9pnVHrX8qx7AHMiYWT+NDAA7jChlNgRS4WTLc/fD1lXLmPixluj+3Gg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-string-parser": "^7.29.7",
+        "@babel/helper-validator-identifier": "^7.29.7"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@bcoe/v8-coverage": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-1.0.2.tgz",
+      "integrity": "sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@bramus/specificity": {
       "version": "2.4.2",
       "resolved": "https://registry.npmjs.org/@bramus/specificity/-/specificity-2.4.2.tgz",
@@ -256,6 +317,16 @@
         }
       }
     },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/@jridgewell/sourcemap-codec": {
       "version": "1.5.5",
       "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
@@ -263,6 +334,17 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.2.2.tgz",
@@ -395,9 +477,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -415,9 +494,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -435,9 +511,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -455,9 +528,6 @@
         "s390x"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -475,9 +545,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -495,9 +562,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -624,6 +688,37 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@vitest/coverage-v8": {
+      "version": "4.1.10",
+      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.10.tgz",
+      "integrity": "sha512-IM49HmthevbgAO4anp1hwtoT9wYe59w0LR00gr+eagHE+ZJ5lK4sLPeO0ubgoJcwLk6dehU3R24N+FbEEKDc8g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@bcoe/v8-coverage": "^1.0.2",
+        "@vitest/utils": "4.1.10",
+        "ast-v8-to-istanbul": "^1.0.0",
+        "istanbul-lib-coverage": "^3.2.2",
+        "istanbul-lib-report": "^3.0.1",
+        "istanbul-reports": "^3.2.0",
+        "magicast": "^0.5.2",
+        "obug": "^2.1.1",
+        "std-env": "^4.0.0-rc.1",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@vitest/browser": "4.1.10",
+        "vitest": "4.1.10"
+      },
+      "peerDependenciesMeta": {
+        "@vitest/browser": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@vitest/expect": {
       "version": "4.1.10",
       "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.10.tgz",
@@ -769,6 +864,18 @@
         "node": ">=12"
       }
     },
+    "node_modules/ast-v8-to-istanbul": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/ast-v8-to-istanbul/-/ast-v8-to-istanbul-1.0.5.tgz",
+      "integrity": "sha512-UPAgKJFSEGMWSDr3LX4tqnAb4f7KGT8O40Tyx8wbYmmZ/yn58lNCm8h3svs3eXgiGd5AXxz8NDOvXWvicq+rJA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "^0.3.31",
+        "estree-walker": "^3.0.3",
+        "js-tokens": "^10.0.0"
+      }
+    },
     "node_modules/bidi-js": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
@@ -943,6 +1050,16 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
+    "node_modules/has-flag": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
+      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/hls.js": {
       "version": "1.6.16",
       "resolved": "https://registry.npmjs.org/hls.js/-/hls.js-1.6.16.tgz",
@@ -962,6 +1079,13 @@
         "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
       }
     },
+    "node_modules/html-escaper": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
+      "integrity": "sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/is-potential-custom-element-name": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
@@ -969,6 +1093,52 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/istanbul-lib-coverage": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
+      "integrity": "sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/istanbul-lib-report": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz",
+      "integrity": "sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "istanbul-lib-coverage": "^3.0.0",
+        "make-dir": "^4.0.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/istanbul-reports": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/istanbul-reports/-/istanbul-reports-3.2.0.tgz",
+      "integrity": "sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "html-escaper": "^2.0.0",
+        "istanbul-lib-report": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/js-tokens": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-10.0.0.tgz",
+      "integrity": "sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/jsdom": {
       "version": "30.0.1",
       "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-30.0.1.tgz",
@@ -1153,9 +1323,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -1177,9 +1344,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -1201,9 +1365,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -1225,9 +1386,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -1303,6 +1461,34 @@
         "@jridgewell/sourcemap-codec": "^1.5.5"
       }
     },
+    "node_modules/magicast": {
+      "version": "0.5.4",
+      "resolved": "https://registry.npmjs.org/magicast/-/magicast-0.5.4.tgz",
+      "integrity": "sha512-llBEhWm1SacoRwgHUoQJYtwp4PBLF4faQi5TCpIGyGs9n4y5+juI0tDgyKIfpqxckRHaHzouUEph3THklWh03w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.29.7",
+        "@babel/types": "^7.29.7",
+        "source-map-js": "^1.2.1"
+      }
+    },
+    "node_modules/make-dir": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
+      "integrity": "sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "semver": "^7.5.3"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/mdn-data": {
       "version": "2.27.1",
       "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz",
@@ -1321,9 +1507,9 @@
       }
     },
     "node_modules/nanoid": {
-      "version": "3.3.16",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.16.tgz",
-      "integrity": "sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==",
+      "version": "3.3.18",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
+      "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
       "dev": true,
       "funding": [
         {
@@ -1489,6 +1675,19 @@
         "node": ">=v12.22.7"
       }
     },
+    "node_modules/semver": {
+      "version": "7.8.5",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/siginfo": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
@@ -1535,6 +1734,19 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/supports-color": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/symbol-tree": {
       "version": "3.2.4",
       "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",

frontend/package.json

@@ -1,17 +1,22 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "1.0.11",
+  "version": "1.0.13",
   "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
     "preview": "vite preview",
     "lint": "tsc --noEmit",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.10",
     "@vitest/ui": "^4.1.10",
     "jsdom": "^30.0.1",
     "typescript": "~6.0.2",

frontend/public/admin/chat-log.html

@@ -21,7 +21,7 @@
 
 <div class="panel-card">
   <div class="table-wrap">
-    <table class="data-table">
+    <table class="data-table chat-log-table">
       <thead>
         <tr>
           <th><input type="checkbox" id="chat-log-select-all" title="Select all" /></th>
@@ -43,4 +43,4 @@
     <button id="chat-log-next-btn" type="button" class="btn btn-secondary" disabled>Next</button>
   </div>
   <p id="chat-log-status" class="status-line" aria-live="polite">Loading chat log...</p>
-</div>
+</div>

frontend/public/admin/system.html

@@ -56,8 +56,13 @@
 <div class="panel-card">
   <h2>Runtime Configuration</h2>
   <form id="config-form" class="form-stack" style="max-width: 400px">
+    <label>HLS Segment Duration (seconds) <input id="config-hls-duration" type="number" min="2" max="15" class="text-input" /></label>
+    <label>HLS Window Size (segments) <input id="config-hls-window" type="number" min="3" max="100" class="text-input" /></label>
+    <label>Matomo URL <input id="config-matomo-url" type="url" class="text-input" placeholder="https://..." /></label>
+    <label>Matomo Site ID <input id="config-matomo-site-id" type="text" class="text-input" /></label>
     <label>Rate Limit Max <input id="config-rate-max" type="number" class="text-input" /></label>
     <label>Rate Limit Window (seconds) <input id="config-rate-window" type="number" class="text-input" /></label>
+    <p class="small-muted">HLS changes take effect after restarting the playout service.</p>
     <button type="submit" class="btn btn-primary">Save Config</button>
   </form>
   <p id="config-status" class="status-line" aria-live="polite"></p>

frontend/src/admin.test.ts

@@ -271,3 +271,108 @@ file '/app/media/demo2.mp4'
     expect(list.innerHTML).toContain("demo1.mp4");
   });
 });
+
+describe("admin accessibility", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <nav class="admin-nav" aria-label="Admin navigation">
+        <button data-tab="dashboard" aria-current="page">Dashboard</button>
+        <button data-tab="playlist">Playlist</button>
+        <button data-tab="users">Users</button>
+        <button data-tab="moderation">Moderation</button>
+      </nav>
+      <div id="tab-content"></div>
+    `;
+  });
+
+  it("nav has aria-label for screen readers", () => {
+    const nav = document.querySelector(".admin-nav");
+    expect(nav?.getAttribute("aria-label")).toBe("Admin navigation");
+  });
+
+  it("active tab has aria-current attribute", () => {
+    const active = document.querySelector("[aria-current]");
+    expect(active).toBeTruthy();
+    expect(active?.getAttribute("aria-current")).toBe("page");
+  });
+
+  it("all nav buttons are focusable", () => {
+    const buttons = document.querySelectorAll(".admin-nav button");
+    buttons.forEach((btn) => {
+      expect(btn.getAttribute("tabindex")).toBeNull();
+      expect(btn.getAttribute("disabled")).toBeNull();
+    });
+  });
+});
+
+describe("admin responsive layout", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <nav class="admin-nav"><button data-tab="dashboard">Dashboard</button></nav>
+      <div id="tab-content"><div id="overview-content">Overview data</div></div>
+    `;
+  });
+
+  it("tab content is present and visible", () => {
+    const tabContent = document.getElementById("tab-content");
+    expect(tabContent).toBeTruthy();
+    const style = window.getComputedStyle(tabContent!);
+    expect(style.display).not.toBe("none");
+  });
+
+  it("admin nav contains essential tabs", () => {
+    const buttons = document.querySelectorAll(".admin-nav button");
+    const tabs = Array.from(buttons).map((b) => b.textContent?.trim());
+    expect(tabs).toContain("Dashboard");
+  });
+});
+
+describe("admin data refresh failures", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="overview-status"></div>
+      <div id="analytics-status"></div>
+    `;
+  });
+
+  it("sets error status when overview fails", async () => {
+    mockFetchResponse = { ok: false, status: 500, payload: {} };
+    await refreshOverview();
+    expect(document.getElementById("overview-status")?.textContent).toContain("Failed");
+  });
+
+  it("sets error status when analytics fails", async () => {
+    mockFetchResponse = { ok: false, status: 500, payload: {} };
+    await refreshAnalytics();
+    expect(document.getElementById("analytics-status")?.textContent).toContain("Failed");
+  });
+});
+
+describe("playlist status badges", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `<ul id="playlist-sortable"></ul>`;
+  });
+
+  it("renders badges for every media status", () => {
+    const statusMap = new Map<string, string>([
+      ["/app/media/ready.mp4", "ready"],
+      ["/app/media/needs.mp4", "needs_normalization"],
+      ["/app/media/normalizing.mp4", "normalizing"],
+      ["/app/media/failed.mp4", "normalization_failed"],
+      ["/app/media/other.mp4", "weird"],
+    ]);
+
+    renderPlaylistSortable(
+      "file '/app/media/ready.mp4'\nfile '/app/media/needs.mp4'\nfile '/app/media/normalizing.mp4'\nfile '/app/media/failed.mp4'\nfile '/app/media/other.mp4'\nfile '/app/media/nopath.mp4'\n",
+      statusMap,
+    );
+
+    const list = document.getElementById("playlist-sortable")!;
+    expect(list.innerHTML).toContain("badge-ok");
+    expect(list.innerHTML).toContain("badge-warn");
+    expect(list.innerHTML).toContain("badge-info");
+    expect(list.innerHTML).toContain("badge-danger");
+    expect(list.innerHTML).toContain("badge-muted"); // default + unknown fall back to muted
+    expect(list.children).toHaveLength(6);
+  });
+});

frontend/src/admin.ts

@@ -16,6 +16,7 @@ type MediaEntry = {
   runtime?: string;
   modifiedAt?: string;
   tags?: string;
+  path?: string;
 };
 
 const bodyDataset = document.body.dataset;
@@ -246,7 +247,8 @@ async function refreshPlaylist() {
     const content: string = payload.content || "";
     const textarea = document.getElementById("playlist-content") as HTMLTextAreaElement | null;
     if (textarea) textarea.value = content;
-    renderPlaylistSortable(content);
+    const statusMap = await fetchMediaStatusMap();
+    renderPlaylistSortable(content, statusMap);
     await showPlaylistWarnings(content);
     setStatus("playlist-status", "Playlist loaded.");
   } catch (error) {
@@ -255,7 +257,7 @@ async function refreshPlaylist() {
   }
 }
 
-export function renderPlaylistSortable(content: string) {
+export function renderPlaylistSortable(content: string, statusMap?: Map<string, string>) {
   const list = document.getElementById("playlist-sortable");
   if (!list) return;
   const lines = content.split("\n").filter((l) => l.trim() && !l.startsWith("#"));
@@ -265,10 +267,12 @@ export function renderPlaylistSortable(content: string) {
         .replace(/^file\s+/, "")
         .replace(/['"]/g, "")
         .trim();
+      const badge = statusMap ? statusBadge(statusMap.get(path)) : "";
       return `<li class="sortable-item" draggable="true" data-index="${i}">
         <span class="drag-handle" aria-hidden="true">⋮⋮</span>
         <span class="sortable-index">${i + 1}</span>
         <span class="sortable-path">${path}</span>
+        ${badge}
         <button type="button" class="btn btn-secondary btn-sm" data-remove="${i}">✕</button>
       </li>`;
     })
@@ -352,6 +356,80 @@ async function showPlaylistWarnings(content: string) {
   }
 }
 
+function statusBadge(status: string | undefined): string {
+  if (!status) return `<span class="badge badge-muted">unknown</span>`;
+  switch (status) {
+    case "ready":
+      return `<span class="badge badge-ok">ready</span>`;
+    case "needs_normalization":
+      return `<span class="badge badge-warn">needs normalization</span>`;
+    case "normalizing":
+      return `<span class="badge badge-info">normalizing</span>`;
+    case "normalization_failed":
+      return `<span class="badge badge-danger">failed</span>`;
+    default:
+      return `<span class="badge badge-muted">${status}</span>`;
+  }
+}
+
+async function fetchMediaStatusMap(): Promise<Map<string, string>> {
+  const map = new Map<string, string>();
+  try {
+    const resp = await fetch("/api/admin/media");
+    if (!resp.ok) return map;
+    const payload = await resp.json();
+    for (const f of payload.files || []) {
+      if (f.path) map.set(f.path, f.status || "unknown");
+    }
+  } catch {
+    /* ignore */
+  }
+  return map;
+}
+
+async function addMediaToPlaylist(file: MediaEntry) {
+  if (file.status !== "ready") {
+    setStatus("media-status", "Only ready media can be added to the playlist.", true);
+    return;
+  }
+  if (!file.path) {
+    setStatus("media-status", "Cannot add media without a path.", true);
+    return;
+  }
+  setStatus("media-status", `Adding ${file.name} to playlist...`);
+  try {
+    const getResp = await fetch("/api/admin/playlist");
+    if (!getResp.ok) throw new Error(await readErrorMessage(getResp));
+    const payload = await getResp.json();
+    const content: string = payload.content || "";
+    const lines = content.split("\n").filter((l) => l.trim());
+    const entry = `file '${file.path}'`;
+    const exists = lines.some(
+      (l) =>
+        l
+          .replace(/^file\s+/, "")
+          .replace(/['"]/g, "")
+          .trim() === file.path,
+    );
+    if (exists) {
+      setStatus("media-status", `${file.name} is already in the playlist.`, true);
+      return;
+    }
+    lines.push(entry);
+    const putResp = await fetch("/api/admin/playlist", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ content: lines.join("\n") + "\n" }),
+    });
+    if (!putResp.ok) throw new Error(await readErrorMessage(putResp));
+    setStatus("media-status", `${file.name} added to playlist.`);
+  } catch (error) {
+    console.error("Failed to add media to playlist", error);
+    const details = error instanceof Error ? error.message : "Unknown error.";
+    setStatus("media-status", `Failed to add ${file.name} to playlist. (${details})`, true);
+  }
+}
+
 export async function savePlaylist() {
   if (state.playlistSaving) return;
   state.playlistSaving = true;
@@ -480,6 +558,37 @@ async function deleteOverride(id: number) {
   }
 }
 
+async function renderServiceRow(service: any) {
+  const svcDetail = service.detail || "";
+
+  // playout service returns json detail, all others return ISO formatted time string
+  if (service.name === "playout" && svcDetail) {
+    try {
+      // create a list of key-value pairs for each property in the JSON object
+      const detailObj = JSON.parse(svcDetail);
+      service.detail = Object.entries(detailObj)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n");
+    } catch {
+      // ignore JSON parse errors
+    }
+  }
+
+  const row = document.createElement("article");
+  row.className = "service-row";
+  row.innerHTML = `
+    <div>
+      <h3>${service.name}</h3>
+      <p class="small-muted">${service.checked}</p>
+    </div>
+    <div class="service-row-right">
+      <p class="service-status service-status-${service.status}">${service.status}</p>
+      <p>${service.detail}</p>
+    </div>
+  `;
+  return row;
+}
+
 async function refreshSystemSummary() {
   setStatus("system-status", "Loading system summary...");
   try {
@@ -499,19 +608,9 @@ async function refreshSystemSummary() {
       servicesEl.innerHTML = "";
       const services = (payload.services || []) as ServiceHealth[];
       services.forEach((service) => {
-        const row = document.createElement("article");
-        row.className = "service-row";
-        row.innerHTML = `
-          <div>
-            <h3>${service.name}</h3>
-            <p class="small-muted">${service.checked}</p>
-          </div>
-          <div class="service-row-right">
-            <p class="service-status service-status-${service.status}">${service.status}</p>
-            <p>${service.detail}</p>
-          </div>
-        `;
-        servicesEl.appendChild(row);
+        renderServiceRow(service).then((row) => {
+          servicesEl.appendChild(row);
+        });
       });
     }
 
@@ -534,19 +633,29 @@ function renderMediaRows(files: MediaEntry[]) {
 
   files.forEach((file) => {
     const tr = document.createElement("tr");
+    const canNormalize = file.status === "needs_normalization" || file.status === "normalization_failed";
+    const canAdd = file.status === "ready";
     tr.innerHTML = `
       <td>${file.name}</td>
       <td>${file.title || "-"}</td>
       <td>${file.runtime || "00:00:00"}</td>
-      <td>${file.status || "unknown"}</td>
+      <td>${statusBadge(file.status)}</td>
       <td>${fmtSize(file.size)}</td>
       <td>${file.modifiedAt || "-"}</td>
       <td class="action-cell">
         <button type="button" class="btn btn-secondary btn-small" data-action="edit" data-id="${file.id || ""}">Edit</button>
+        ${canNormalize ? `<button type="button" class="btn btn-secondary btn-small" data-action="normalize" data-id="${file.id || ""}">Normalize</button>` : ""}
+        ${canAdd ? `<button type="button" class="btn btn-secondary btn-small" data-action="add" data-id="${file.id || ""}">Add to playlist</button>` : ""}
         <button type="button" class="btn btn-danger btn-small" data-action="delete" data-id="${file.id || ""}">Delete</button>
       </td>
     `;
     tr.querySelector('[data-action="edit"]')?.addEventListener("click", () => editMedia(file));
+    if (canNormalize) {
+      tr.querySelector('[data-action="normalize"]')?.addEventListener("click", () => normalizeMedia(file));
+    }
+    if (canAdd) {
+      tr.querySelector('[data-action="add"]')?.addEventListener("click", () => addMediaToPlaylist(file));
+    }
     tr.querySelector('[data-action="delete"]')?.addEventListener("click", () => deleteMedia(file));
     tbody.appendChild(tr);
   });
@@ -699,6 +808,55 @@ async function editMedia(file: MediaEntry) {
   }
 }
 
+async function normalizeMedia(file: MediaEntry) {
+  if (!file.id) {
+    setStatus("media-status", "Cannot normalize media item without id.", true);
+    return;
+  }
+
+  setStatus("media-status", `Normalizing ${file.name}...`);
+  try {
+    const response = await fetch(`/api/admin/media/${file.id}/normalize`, { method: "POST" });
+    if (!response.ok) throw new Error(await readErrorMessage(response));
+
+    setStatus("media-status", `Normalization started for ${file.name}.`);
+    await refreshMediaLibrary();
+    pollNormalizationStatus(file.id, 0);
+  } catch (error) {
+    console.error("Failed to normalize media", error);
+    const details = error instanceof Error ? error.message : "Unknown error.";
+    setStatus("media-status", `Failed to normalize ${file.name}. (${details})`, true);
+  }
+}
+
+function pollNormalizationStatus(id: number, attempt: number) {
+  if (attempt >= 60) {
+    setStatus("media-status", "Normalization is taking longer than expected. Reload the library to check.", true);
+    return;
+  }
+  window.setTimeout(async () => {
+    try {
+      const response = await fetch(`/api/admin/media/${id}`);
+      if (!response.ok) return;
+      const file = (await response.json()) as MediaEntry;
+      if (file.status === "normalizing" || file.status === "needs_normalization") {
+        pollNormalizationStatus(id, attempt + 1);
+        return;
+      }
+      await refreshMediaLibrary();
+      await refreshOverview();
+      await refreshSchedule();
+      setStatus(
+        "media-status",
+        file.status === "ready" ? `Normalization complete for ${file.name}.` : `Normalization failed for ${file.name}.`,
+        file.status !== "ready",
+      );
+    } catch {
+      // Stop polling on error; the user can reload the library manually.
+    }
+  }, 3000);
+}
+
 async function deleteMedia(file: MediaEntry) {
   if (!file.id) {
     setStatus("media-status", "Cannot delete media item without id.", true);
@@ -1068,6 +1226,10 @@ async function loadConfig() {
     const cfg = await resp.json();
     (document.getElementById("config-rate-max") as HTMLInputElement).value = cfg.rateLimitMax;
     (document.getElementById("config-rate-window") as HTMLInputElement).value = cfg.rateLimitWindowSec;
+    (document.getElementById("config-hls-duration") as HTMLInputElement).value = cfg.hlsSegmentDuration;
+    (document.getElementById("config-hls-window") as HTMLInputElement).value = cfg.hlsWindowSize;
+    (document.getElementById("config-matomo-url") as HTMLInputElement).value = cfg.matomoUrl || "";
+    (document.getElementById("config-matomo-site-id") as HTMLInputElement).value = cfg.matomoSiteId || "";
   } catch {
     /* non-critical */
   }
@@ -1082,11 +1244,13 @@ async function saveConfig(e: Event) {
       method: "PUT",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        rateLimitMax: Number((document.getElementById("config-rate-max") as HTMLInputElement).value),
-        rateLimitWindowSec: Number((document.getElementById("config-rate-window") as HTMLInputElement).value),
+        hlsSegmentDuration: Number((document.getElementById("config-hls-duration") as HTMLInputElement).value),
+        hlsWindowSize: Number((document.getElementById("config-hls-window") as HTMLInputElement).value),
+        matomoUrl: (document.getElementById("config-matomo-url") as HTMLInputElement).value.trim(),
+        matomoSiteId: (document.getElementById("config-matomo-site-id") as HTMLInputElement).value.trim(),
       }),
     });
-    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    if (!resp.ok) throw new Error(await readErrorMessage(resp));
     if (status) {
       status.textContent = "Config saved.";
       status.className = "status-line";

frontend/src/counter.test.ts

@@ -0,0 +1,23 @@
+/// <reference types="vitest" />
+import { describe, it, expect } from "vitest";
+import { setupCounter } from "../src/counter";
+
+describe("setupCounter", () => {
+  it("initializes the button with count 0", () => {
+    const btn = document.createElement("button");
+    setupCounter(btn);
+    expect(btn.innerHTML).toBe("Count is 0");
+  });
+
+  it("increments the counter on each click", () => {
+    const btn = document.createElement("button");
+    setupCounter(btn);
+
+    btn.click();
+    expect(btn.innerHTML).toBe("Count is 1");
+
+    btn.click();
+    btn.click();
+    expect(btn.innerHTML).toBe("Count is 3");
+  });
+});

frontend/src/main.test.ts

@@ -1,6 +1,12 @@
 /// <reference types="vitest" />
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { resetViewerStateForTests, resolveManifestUrl, resolveWebSocketBaseUrl } from "../src/main";
+import {
+  resetViewerStateForTests,
+  resolveManifestUrl,
+  resolveWebSocketBaseUrl,
+  showReconnecting,
+  hideReconnecting,
+} from "../src/main";
 
 const hlsInstance = {
   loadSource: vi.fn(),
@@ -13,7 +19,17 @@ const HlsMock = Object.assign(
   vi.fn().mockImplementation(() => hlsInstance),
   {
     isSupported: vi.fn(() => true),
-    Events: { MANIFEST_PARSED: "hlsManifestParsed" },
+    Events: {
+      MANIFEST_PARSED: "hlsManifestParsed",
+      ERROR: "hlsError",
+      LEVEL_UPDATED: "hlsLevelUpdated",
+    },
+    ErrorTypes: {
+      NETWORK_ERROR: "networkError",
+      MEDIA_ERROR: "mediaError",
+      MUX_ERROR: "muxError",
+      OTHER_ERROR: "otherError",
+    },
   },
 );
 
@@ -63,35 +79,64 @@ beforeEach(() => {
   });
 
   // Set up DOM from index.html
+  // Inject minimal CSS for jsdom layout tests (external style.css not loaded)
+  document.head.innerHTML = `
+    <style>
+      .viewer-content { display: grid; grid-template-columns: minmax(0, 1fr) minmax(300px, 420px); }
+      .viewer-shell.chat-collapsed .chat-sidebar { display: none; }
+    </style>
+  `;
+
   document.body.innerHTML = `
     <main class="viewer-shell">
       <header class="viewer-header">
-        <button id="chat-toggle" type="button">Hide Chat</button>
+        <button id="chat-toggle" type="button" aria-expanded="true">Hide Chat</button>
       </header>
       <section class="viewer-content">
         <section class="player-stage">
           <video id="player" class="player" controls autoplay muted playsinline></video>
-          <div id="now-playing">
+          <div id="now-playing" aria-live="polite">
             <span id="np-title">Loading...</span>
             <span id="np-next" class="np-next"></span>
           </div>
         </section>
-        <aside id="chat-panel" class="chat-sidebar">
+        <aside id="chat-panel" class="chat-sidebar" role="complementary" aria-label="Chat panel">
           <div class="chat-header">
             <span id="room-name">Main Channel</span>
             <button type="button" onclick="togglePrivateDM()">New DM</button>
           </div>
-          <section id="messages" class="chat-messages"></section>
+          <div id="chat-flash" class="chat-flash" aria-live="polite" hidden></div>
+          <section id="messages" class="chat-messages" aria-live="polite"></section>
           <section id="presence-panel" class="presence-panel">
             <div id="presence-list" class="presence-list"></div>
           </section>
           <div class="chat-input-area">
+            <label for="message-input">Message input</label>
             <input id="message-input" type="text" placeholder="Type a message..." />
             <button type="button" onclick="sendMessage()">Send</button>
           </div>
         </aside>
       </section>
     </main>
+    <div id="reconnecting-overlay" role="alert" aria-live="assertive" hidden>
+      <span id="reconnecting-text">Reconnecting...</span>
+    </div>
+    <div id="chat-user-label" hidden></div>
+    <button id="auth-toggle-btn" type="button">Sign in</button>
+    <button id="auth-logout-btn" type="button" hidden>Logout</button>
+    <div id="auth-panel" hidden>
+      <input id="auth-username" type="text" />
+      <input id="auth-password" type="password" />
+      <span id="auth-status"></span>
+      <button id="auth-login-btn" type="button">Login</button>
+      <button id="auth-register-btn" type="button">Register</button>
+    </div>
+    <button id="users-toggle-btn" type="button" aria-expanded="true">Users</button>
+    <div id="typing-indicator" hidden></div>
+    <div id="dm-search-row" hidden>
+      <input id="dm-search-input" type="text" />
+      <button id="dm-search-btn" type="button">Search</button>
+    </div>
   `;
 
   // Stub prompt for DM
@@ -208,6 +253,25 @@ describe("WebSocket reconnect", () => {
     expect(websocketInstances).toHaveLength(2);
     expect(websocketInstances[1].url).toContain("room=lobby");
   });
+
+  it("does not reconnect from a socket that was intentionally replaced", async () => {
+    vi.useFakeTimers();
+
+    window.switchRoom("lobby");
+    expect(websocketInstances).toHaveLength(1);
+    const replaced = websocketInstances[0];
+
+    // A room switch intentionally replaces the socket; the old socket must not
+    // schedule its own reconnect, otherwise history is re-pulled on a loop.
+    window.switchRoom("main");
+    expect(websocketInstances).toHaveLength(2);
+    expect(replaced.onclose).toBeNull();
+
+    replaced.onclose?.();
+    await vi.advanceTimersByTimeAsync(3000);
+
+    expect(websocketInstances).toHaveLength(2);
+  });
 });
 
 describe("URL resolution", () => {
@@ -331,8 +395,229 @@ describe("message rendering", () => {
     });
 
     const messages = document.getElementById("messages")!;
-    expect(messages.innerHTML).toContain("alice");
     expect(messages.innerHTML).toContain("hey");
+    expect(messages.innerHTML).toContain("alice");
     expect(messages.querySelector(".message-other")).toBeTruthy();
   });
 });
+
+describe("reconnecting overlay", () => {
+  it("shows and hides the overlay with a custom message", () => {
+    showReconnecting("Custom message");
+    const overlay = document.getElementById("reconnecting-overlay")!;
+    expect(overlay.classList.contains("hidden")).toBe(false);
+    expect(document.getElementById("reconnecting-text")!.textContent).toBe("Custom message");
+
+    hideReconnecting();
+    expect(overlay.classList.contains("hidden")).toBe(true);
+  });
+});
+
+describe("typing indicator", () => {
+  it("shows typing on a typing event and clears on the next message", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "typing", username: "alice" }) });
+
+    const indicator = document.getElementById("typing-indicator")!;
+    expect(indicator.textContent).toBe("alice is typing...");
+    expect(indicator.hidden).toBe(false);
+
+    ws.onmessage?.({ data: JSON.stringify({ type: "public", text: "hi", username: "alice", timestamp: Date.now() }) });
+    expect(indicator.hidden).toBe(true);
+    expect(indicator.textContent).toBe("");
+  });
+
+  it("ignores typing events from the current user", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "typing", username: "viewer" }) });
+
+    const indicator = document.getElementById("typing-indicator")!;
+    expect(indicator.textContent).toBe("");
+    expect(indicator.hidden).toBe(true);
+  });
+});
+
+describe("sendMessage over websocket", () => {
+  it("sends a JSON message and clears the input", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const input = document.getElementById("message-input") as HTMLInputElement;
+    input.value = "hello world";
+    window.sendMessage();
+
+    const ws = websocketInstances[0];
+    expect(ws.send).toHaveBeenCalledTimes(1);
+    expect(ws.send).toHaveBeenCalledWith(expect.stringContaining("hello world"));
+    expect(input.value).toBe("");
+  });
+});
+
+describe("auth and user list wiring", () => {
+  it("logs in and updates the auth UI", async () => {
+    await import("../src/main");
+
+    globalThis.fetch = vi.fn(async (url: any) => {
+      const u = String(url);
+      if (u.includes("/api/auth/login")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ username: "alice", authenticated: true }),
+          text: async () => "",
+        };
+      }
+      return { ok: true, status: 200, json: async () => ({ authenticated: false }), text: async () => "" };
+    }) as any;
+
+    document.dispatchEvent(new Event("DOMContentLoaded"));
+
+    const usernameInput = document.getElementById("auth-username") as HTMLInputElement;
+    const passwordInput = document.getElementById("auth-password") as HTMLInputElement;
+    usernameInput.value = "alice";
+    passwordInput.value = "secret";
+
+    document.getElementById("auth-login-btn")!.click();
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(document.getElementById("auth-status")!.textContent).toContain("Signed in as alice");
+    expect(document.getElementById("chat-user-label")!.textContent).toBe("alice");
+  });
+
+  it("toggles the user list visibility", async () => {
+    await import("../src/main");
+
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ authenticated: false, entries: [] }),
+      text: async () => "",
+    }) as any;
+
+    document.dispatchEvent(new Event("DOMContentLoaded"));
+
+    const panel = document.getElementById("presence-panel")!;
+    const btn = document.getElementById("users-toggle-btn")!;
+    expect(panel.hidden).toBe(false);
+
+    btn.click();
+    expect(panel.hidden).toBe(true);
+    expect(btn.getAttribute("aria-expanded")).toBe("false");
+
+    btn.click();
+    expect(panel.hidden).toBe(false);
+    expect(btn.getAttribute("aria-expanded")).toBe("true");
+  });
+});
+
+describe("player error recovery", () => {
+  it("shows reconnecting overlay on fatal network error", async () => {
+    const main = await import("../src/main");
+    await main.initPlayerAndChat(async () => ({ default: HlsMock }) as any);
+
+    // Find the error handler registered by initPlayerAndChat
+    const errorHandler = (hlsInstance.on as any).mock.calls.find((c: any) => c[0] === "hlsError") as
+      | [string, Function]
+      | undefined;
+
+    if (errorHandler) {
+      const handler = errorHandler[1];
+      handler("hlsError", {
+        type: "networkError",
+        details: "manifestLoadError",
+        fatal: true,
+      });
+
+      const overlay = document.getElementById("reconnecting-overlay")!;
+      expect(overlay.classList.contains("hidden")).toBe(false);
+      expect(document.getElementById("reconnecting-text")?.textContent).toBe("Reconnecting...");
+    }
+  });
+});
+
+describe("accessibility", () => {
+  it("player video has controls and aria attributes", () => {
+    const video = document.getElementById("player") as HTMLVideoElement;
+    expect(video.controls).toBe(true);
+    expect(video.hasAttribute("autoplay")).toBe(true);
+    expect(video.hasAttribute("playsinline")).toBe(true);
+  });
+
+  it("chat panel has aria-labels for live region", () => {
+    const messages = document.getElementById("messages");
+    expect(messages?.getAttribute("aria-live")).toBe("polite");
+
+    const chatPanel = document.getElementById("chat-panel");
+    expect(chatPanel?.getAttribute("aria-label")).toBe("Chat panel");
+  });
+
+  it("chat toggle exposes aria-expanded state", () => {
+    const toggle = document.getElementById("chat-toggle")!;
+    expect(toggle.getAttribute("aria-expanded")).toBe("true");
+
+    window.toggleChatPanel();
+    expect(toggle.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("message input has associated label", () => {
+    const input = document.getElementById("message-input") as HTMLInputElement;
+    expect(input.getAttribute("type")).toBe("text");
+    expect(input.placeholder).toBe("Type a message...");
+    const label = document.querySelector("label[for='message-input']");
+    expect(label).toBeTruthy();
+    expect(label?.textContent).toBe("Message input");
+  });
+
+  it("reconnecting overlay is an aria-live assertive region", () => {
+    const overlay = document.getElementById("reconnecting-overlay");
+    expect(overlay?.getAttribute("role")).toBe("alert");
+    expect(overlay?.getAttribute("aria-live")).toBe("assertive");
+  });
+});
+
+describe("responsive layout", () => {
+  it("chat-collapsed class hides sidebar at narrow viewport", () => {
+    const shell = document.querySelector(".viewer-shell")!;
+    expect(shell.classList.contains("chat-collapsed")).toBe(false);
+
+    window.toggleChatPanel();
+    expect(shell.classList.contains("chat-collapsed")).toBe(true);
+
+    window.toggleChatPanel();
+    expect(shell.classList.contains("chat-collapsed")).toBe(false);
+  });
+
+  it("viewer-shell uses CSS grid for content layout", () => {
+    const content = document.querySelector(".viewer-content");
+    expect(content).toBeTruthy();
+    const style = window.getComputedStyle(content!);
+    expect(style.display).toBe("grid");
+  });
+
+  it("now-playing overlay is accessible at small sizes", () => {
+    const np = document.getElementById("now-playing");
+    expect(np?.getAttribute("aria-live")).toBe("polite");
+  });
+});
+
+describe("presence flash", () => {
+  it("flashes join/leave messages instead of appending chat rows", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "alice joined the room", username: "system" }) });
+
+    const flash = document.getElementById("chat-flash")!;
+    expect(flash.textContent).toBe("alice joined");
+    expect(flash.hidden).toBe(false);
+
+    // Join/leave must not be rendered as chat rows.
+    const messages = document.getElementById("messages")!;
+    expect(messages.textContent).not.toContain("joined");
+
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "alice left the room", username: "system" }) });
+    expect(flash.textContent).toBe("alice left");
+  });
+});

frontend/src/main.ts

@@ -15,16 +15,34 @@ let hls: InstanceType<HlsClass> | null = null;
 let ws: WebSocket | null = null;
 let currentRoom = "main";
 let username = "viewer" + Math.floor(Math.random() * 1000);
+let authenticated = false;
+let currentDMTarget = "";
 let chatVisible = true;
+let usersVisible = true;
+let typingUser = "";
+let lastTypingSent = 0;
+let typingTimeout: number | undefined;
+let flashTimeout: number | undefined;
+let flashFadeTimeout: number | undefined;
 const onlineUsers = new Set<string>();
 
+// Player error recovery state (STREAMING.md contract)
+let playerErrorCount = 0;
+const PLAYER_MAX_RETRIES = 5;
+const PLAYER_BASE_DELAY_MS = 2000;
+
 export function resetViewerStateForTests() {
   hls = null;
   ws = null;
   currentRoom = "main";
   username = "viewer";
+  authenticated = false;
   chatVisible = true;
+  usersVisible = true;
+  typingUser = "";
+  lastTypingSent = 0;
   onlineUsers.clear();
+  playerErrorCount = 0;
 }
 
 export function resolveWebSocketBaseUrl() {
@@ -61,44 +79,67 @@ export function resolveManifestUrl() {
 }
 
 function connectWebSocket(room: string) {
-  if (ws) ws.close();
+  // Detach the old socket's close handler before closing it. Otherwise an
+  // intentional reconnect (login/logout/room switch/session refresh) would
+  // have the replaced socket schedule yet another reconnect, and each new
+  // connection re-pulls the room's history — filling the panel with old
+  // messages on a loop.
+  if (ws) {
+    ws.onclose = null;
+    ws.close();
+  }
 
   const socketUrl = new URL(resolveWebSocketBaseUrl());
   socketUrl.searchParams.set("username", username);
   socketUrl.searchParams.set("room", room);
-  ws = new WebSocket(socketUrl);
+  const socket = new WebSocket(socketUrl);
+  ws = socket;
 
-  ws.onopen = () => {
+  socket.onopen = () => {
     console.log(`Connected to chat room: ${room}`);
     addMessage("system", "Connected to " + room);
   };
 
-  ws.onmessage = (event) => {
+  socket.onmessage = (event) => {
     const msg = JSON.parse(event.data);
-    addMessage(msg.type || "public", msg.text, msg.username, msg.timestamp);
+    if (msg.type === "typing") {
+      showTyping(msg.username);
+      return;
+    }
+    hideTyping(msg.username);
 
-    // Track presence from system join/leave messages
+    // Presence join/leave announcements become transient flashes, not chat rows.
     if (msg.type === "system" && msg.username === "system") {
       const joined = msg.text?.match(/^(\S+) joined /);
       const left = msg.text?.match(/^(\S+) left /);
       if (joined) {
         onlineUsers.add(joined[1]);
         renderPresence();
+        showFlash(`${joined[1]} joined`);
+        return;
       } else if (left) {
         onlineUsers.delete(left[1]);
         renderPresence();
+        showFlash(`${left[1]} left`);
+        return;
       }
     }
+
+    addMessage(msg.type || "public", msg.text, msg.username, msg.timestamp);
   };
 
-  ws.onclose = () => {
+  socket.onclose = () => {
+    // Ignore close events from sockets that were intentionally replaced.
+    if (ws !== socket) return;
+    ws = null;
     console.log("Chat disconnected. Reconnecting in 3s...");
     setTimeout(() => connectWebSocket(room), 3000);
   };
 }
 
 function addMessage(type: string, text: string, sender = "", timestamp = new Date()) {
-  const messages = document.getElementById("messages")!;
+  const messages = document.getElementById("messages");
+  if (!messages) return;
   const div = document.createElement("div");
   div.className = "message-row";
 
@@ -120,6 +161,23 @@ function addMessage(type: string, text: string, sender = "", timestamp = new Dat
   messages.scrollTop = messages.scrollHeight;
 }
 
+function showFlash(text: string) {
+  const el = document.getElementById("chat-flash");
+  if (!el) return;
+  el.textContent = text;
+  el.hidden = false;
+  el.classList.remove("fade-out");
+  window.clearTimeout(flashTimeout);
+  window.clearTimeout(flashFadeTimeout);
+  flashTimeout = window.setTimeout(() => {
+    el.classList.add("fade-out");
+    flashFadeTimeout = window.setTimeout(() => {
+      el.hidden = true;
+      el.classList.remove("fade-out");
+    }, 500);
+  }, 3000);
+}
+
 function renderPresence() {
   const list = document.getElementById("presence-list");
   if (!list) return;
@@ -131,7 +189,8 @@ function renderPresence() {
 
 async function refreshSchedule() {
   try {
-    const res = await fetch("/api/schedule");
+    const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
+    const res = await fetch(`${apiUrl}/api/schedule`);
     if (!res.ok) return;
     const data = await res.json();
     const entries = data.entries as Array<{ title: string; status: string }>;
@@ -159,10 +218,62 @@ export async function initPlayerAndChat(loadHlsModule: () => Promise<{ default:
     try {
       const { default: Hls } = await loadHlsModule();
       if (Hls.isSupported()) {
-        hls = new Hls();
+        hls = new Hls({
+          liveDurationInfinity: true,
+          liveSyncDurationCount: 3,
+        });
         hls.loadSource(manifestUrl);
         hls.attachMedia(video);
         hls.on(Hls.Events.MANIFEST_PARSED, () => video.play());
+
+        // Player error recovery (STREAMING.md contract)
+        hls.on(Hls.Events.ERROR, (_event, data) => {
+          if (!data.fatal) return;
+
+          playerErrorCount++;
+
+          switch (data.type) {
+            case Hls.ErrorTypes.NETWORK_ERROR:
+              if (playerErrorCount <= PLAYER_MAX_RETRIES) {
+                const delay = PLAYER_BASE_DELAY_MS * Math.pow(2, playerErrorCount - 1);
+                console.warn(
+                  `HLS network error (attempt ${playerErrorCount}/${PLAYER_MAX_RETRIES}), retrying in ${delay}ms...`,
+                );
+                showReconnecting("Reconnecting...");
+                setTimeout(() => {
+                  hls?.startLoad();
+                }, delay);
+              } else {
+                console.error("HLS network error: max retries exhausted");
+                showReconnecting("Stream temporarily unavailable");
+              }
+              break;
+
+            case Hls.ErrorTypes.MEDIA_ERROR:
+              if (playerErrorCount <= 1) {
+                console.warn("HLS media error, attempting recovery...");
+                showReconnecting("Recovering...");
+                hls!.recoverMediaError();
+              } else {
+                console.error("HLS media error: recovery failed");
+                hls!.destroy();
+                showReconnecting("Stream temporarily unavailable");
+              }
+              break;
+
+            default:
+              console.error("HLS fatal error:", data.type, data.details);
+              hls!.destroy();
+              showReconnecting("Stream temporarily unavailable");
+              break;
+          }
+        });
+
+        // Reset error count on successful manifest parse
+        hls.on(Hls.Events.MANIFEST_PARSED, () => {
+          playerErrorCount = 0;
+          hideReconnecting();
+        });
       }
     } catch (error) {
       console.error("Failed to load HLS player", error);
@@ -179,6 +290,24 @@ export async function initPlayerAndChat(loadHlsModule: () => Promise<{ default:
   console.log("Linear Void Frontend initialized - HLS Player + Chat Sidebar ready");
 }
 
+export function showReconnecting(message = "Reconnecting...") {
+  const overlay = document.getElementById("reconnecting-overlay");
+  const text = document.getElementById("reconnecting-text");
+  if (overlay) {
+    overlay.classList.remove("hidden");
+  }
+  if (text) {
+    text.textContent = message;
+  }
+}
+
+export function hideReconnecting() {
+  const overlay = document.getElementById("reconnecting-overlay");
+  if (overlay) {
+    overlay.classList.add("hidden");
+  }
+}
+
 function toggleChatPanel() {
   const shell = document.querySelector(".viewer-shell");
   const toggle = document.getElementById("chat-toggle");
@@ -208,25 +337,199 @@ function sendMessage() {
 
 function switchRoom(room: string) {
   currentRoom = room;
+  const isDM = room.startsWith("dm:");
   document.getElementById("room-name")!.textContent =
     room === "main" ? "Main Channel" : room.charAt(0).toUpperCase() + room.slice(1) + " Room";
   addMessage("system", `Switched to ${room} room`);
+  const searchRow = document.getElementById("dm-search-row");
+  if (searchRow) searchRow.hidden = !isDM;
   connectWebSocket(room);
 }
 
 function togglePrivateDM() {
   const target = prompt("Enter username to start private chat with:");
   if (target && target !== username) {
+    currentDMTarget = target;
     const dmRoom = `dm:${[username, target].sort().join("-")}`;
     switchRoom(dmRoom);
   }
 }
 
+async function searchDM() {
+  const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
+  const input = document.getElementById("dm-search-input") as HTMLInputElement;
+  const q = input.value.trim();
+  if (!q || !currentDMTarget) return;
+  try {
+    const res = await fetch(
+      `${apiUrl}/api/dm/search?with=${encodeURIComponent(currentDMTarget)}&q=${encodeURIComponent(q)}`,
+      { credentials: "include" },
+    );
+    if (!res.ok) return;
+    const results = await res.json();
+    addMessage("system", `Search results (${results.length}) for "${q}":`);
+    for (const m of results) {
+      addMessage(m.type || "private", m.text, m.username, m.timestamp);
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
 window.switchRoom = switchRoom;
 window.sendMessage = sendMessage;
 window.togglePrivateDM = togglePrivateDM;
 window.toggleChatPanel = toggleChatPanel;
 
+function updateAuthUI() {
+  const label = document.getElementById("chat-user-label");
+  const toggle = document.getElementById("auth-toggle-btn");
+  const logoutBtn = document.getElementById("auth-logout-btn");
+  const panel = document.getElementById("auth-panel");
+  if (label) {
+    label.textContent = authenticated ? username : "";
+    label.hidden = !authenticated;
+  }
+  if (toggle) toggle.hidden = authenticated;
+  if (logoutBtn) logoutBtn.hidden = !authenticated;
+  if (panel) panel.hidden = true;
+}
+
+async function refreshUserSession() {
+  try {
+    const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
+    const res = await fetch(`${apiUrl}/api/auth/session`, { credentials: "include" });
+    if (!res.ok) return;
+    const data = await res.json();
+    const wasAnonymous = username.startsWith("viewer");
+    if (data.authenticated && data.username) {
+      authenticated = true;
+      username = data.username;
+      updateAuthUI();
+      if (wasAnonymous) connectWebSocket(currentRoom);
+    } else {
+      authenticated = false;
+      updateAuthUI();
+    }
+  } catch {
+    /* non-critical */
+  }
+}
+
+async function submitAuth(path: string) {
+  const u = (document.getElementById("auth-username") as HTMLInputElement).value.trim();
+  const p = (document.getElementById("auth-password") as HTMLInputElement).value;
+  const status = document.getElementById("auth-status");
+  if (!u || !p) {
+    if (status) {
+      status.textContent = "Username and password required.";
+      status.className = "status-line status-error";
+    }
+    return;
+  }
+  try {
+    const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
+    const res = await fetch(`${apiUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ username: u, password: p }),
+    });
+    if (!res.ok) {
+      const text = (await res.text()).trim();
+      throw new Error(text || `HTTP ${res.status}`);
+    }
+    const data = await res.json();
+    username = data.username || u;
+    authenticated = true;
+    updateAuthUI();
+    if (status) {
+      status.textContent = `Signed in as ${username}.`;
+      status.className = "status-line";
+    }
+    connectWebSocket(currentRoom);
+  } catch (err) {
+    if (status) {
+      status.textContent = `Failed: ${err instanceof Error ? err.message : String(err)}`;
+      status.className = "status-line status-error";
+    }
+  }
+}
+
+function login() {
+  void submitAuth("/api/auth/login");
+}
+
+function register() {
+  void submitAuth("/api/auth/register");
+}
+
+async function logout() {
+  try {
+    const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
+    await fetch(`${apiUrl}/api/auth/logout`, { method: "POST", credentials: "include" });
+  } catch {
+    /* ignore */
+  }
+  authenticated = false;
+  username = "viewer" + Math.floor(Math.random() * 1000);
+  updateAuthUI();
+  connectWebSocket(currentRoom);
+}
+
+function toggleUserList() {
+  const panel = document.getElementById("presence-panel");
+  const btn = document.getElementById("users-toggle-btn");
+  if (!panel) return;
+  usersVisible = !usersVisible;
+  panel.hidden = !usersVisible;
+  if (btn) btn.setAttribute("aria-expanded", String(usersVisible));
+}
+
+function showTyping(name: string) {
+  if (name === username) return;
+  const el = document.getElementById("typing-indicator");
+  if (!el) return;
+  typingUser = name;
+  el.textContent = `${name} is typing...`;
+  el.hidden = false;
+  window.clearTimeout(typingTimeout);
+  typingTimeout = window.setTimeout(() => {
+    typingUser = "";
+    el.hidden = true;
+    el.textContent = "";
+  }, 3000);
+}
+
+function hideTyping(name: string) {
+  if (name !== typingUser) return;
+  const el = document.getElementById("typing-indicator");
+  typingUser = "";
+  window.clearTimeout(typingTimeout);
+  if (el) {
+    el.hidden = true;
+    el.textContent = "";
+  }
+}
+
+function sendTyping() {
+  if (!ws || ws.readyState !== WebSocket.OPEN) return;
+  const now = Date.now();
+  if (now - lastTypingSent < 2000) return;
+  lastTypingSent = now;
+  ws.send(JSON.stringify({ room: currentRoom, username, text: "", type: "typing" }));
+}
+
 document.addEventListener("DOMContentLoaded", () => {
   void initPlayerAndChat();
+  void refreshUserSession();
+  document.getElementById("auth-toggle-btn")?.addEventListener("click", () => {
+    const panel = document.getElementById("auth-panel");
+    if (panel) panel.hidden = !panel.hidden;
+  });
+  document.getElementById("auth-login-btn")?.addEventListener("click", login);
+  document.getElementById("auth-register-btn")?.addEventListener("click", register);
+  document.getElementById("auth-logout-btn")?.addEventListener("click", logout);
+  document.getElementById("dm-search-btn")?.addEventListener("click", searchDM);
+  document.getElementById("users-toggle-btn")?.addEventListener("click", toggleUserList);
+  document.getElementById("message-input")?.addEventListener("input", sendTyping);
 });

frontend/src/style.css

@@ -1,7 +1,8 @@
 :root {
   color-scheme: dark;
 
-  --font-body: "Atkinson Hyperlegible", "Segoe UI", "Helvetica Neue", sans-serif;
+  --font-body: "Tektur", "Segoe UI", "Helvetica Neue", sans-serif;
+  --font-heading: "Doto", "Segoe UI", "Helvetica Neue", sans-serif;
   --font-display: "Space Grotesk", "Segoe UI", sans-serif;
   --font-mono: "IBM Plex Mono", Consolas, monospace;
 
@@ -125,7 +126,7 @@ h1,
 h2,
 h3 {
   margin: 0;
-  font-family: var(--font-display);
+  font-family: var(--font-heading);
   color: var(--ink-0);
   letter-spacing: -0.02em;
 }
@@ -253,6 +254,101 @@ select {
   line-height: 1.5;
 }
 
+.badge {
+  display: inline-block;
+  padding: 0.1rem 0.5rem;
+  border-radius: 999px;
+  font-size: 0.72rem;
+  font-weight: 600;
+  line-height: 1.5;
+  white-space: nowrap;
+}
+
+.badge-ok {
+  color: var(--ok);
+  background: rgba(4, 101, 13, 0.12);
+}
+
+.badge-warn {
+  color: var(--warn);
+  background: rgba(212, 150, 36, 0.12);
+}
+
+.badge-info {
+  color: var(--brand);
+  background: rgba(88, 119, 146, 0.14);
+}
+
+.badge-danger {
+  color: var(--danger);
+  background: rgba(196, 74, 94, 0.12);
+}
+
+.badge-muted {
+  color: var(--ink-soft);
+  background: var(--bg-2);
+}
+
+.chat-header-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.chat-user-label {
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--ink-soft);
+  max-width: 10rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.auth-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  padding: 0.75rem;
+  border-top: 1px solid var(--bg-2);
+}
+
+.dm-search-row {
+  display: flex;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border-top: 1px solid var(--bg-2);
+}
+
+.typing-indicator {
+  font-size: 0.78rem;
+  font-style: italic;
+  color: var(--ink-soft);
+  padding: 0.25rem 0.75rem 0;
+}
+
+.chat-flash {
+  position: absolute;
+  top: 0.5rem;
+  left: 0.5rem;
+  right: 0.5rem;
+  z-index: 5;
+  padding: 0.4rem 0.75rem;
+  font-size: 0.83rem;
+  text-align: center;
+  color: var(--ink-0);
+  background: color-mix(in srgb, var(--brand) 30%, var(--panel-2));
+  border: 1px solid var(--line);
+  border-radius: var(--radius-1);
+  opacity: 1;
+  transition: opacity 0.5s ease;
+  pointer-events: none;
+}
+
+.chat-flash.fade-out {
+  opacity: 0;
+}
+
 .btn {
   border: 1px solid transparent;
   border-radius: var(--radius-1);
@@ -350,6 +446,10 @@ select {
   color: var(--ink-1);
 }
 
+.chat-log-filters input {
+  padding: 0.2rem 0.5rem;
+}
+
 .table-wrap {
   width: 100%;
   overflow-x: auto;
@@ -376,6 +476,11 @@ select {
   letter-spacing: 0.05em;
 }
 
+#chat-log-table-body td {
+  font-size: 0.72rem;
+  color: var(--ink-0);
+}
+
 .action-cell {
   display: flex;
   flex-wrap: wrap;
@@ -466,7 +571,7 @@ select {
 
 .brand-text,
 .viewer-title {
-  font-family: var(--font-display);
+  font-family: var(--font-heading);
 }
 
 .viewer-title {
@@ -567,6 +672,7 @@ select {
   display: grid;
   grid-template-rows: auto 1fr auto;
   min-height: 0;
+  position: relative;
 }
 
 .chat-header,
@@ -661,12 +767,12 @@ select {
 }
 
 .message-system {
-  font-size: 0.83rem;
+  font-size: 0.7rem;
   color: var(--ink-1);
   background: color-mix(in srgb, var(--brand) 22%, var(--panel-2));
   border: 1px solid color-mix(in srgb, var(--brand) 45%, var(--line));
   border-radius: 0;
-  padding: 0.24rem 0.68rem;
+  padding: 0.2rem 0.5rem;
   animation: messageIn var(--fast);
 }
 
@@ -678,6 +784,7 @@ select {
 
 .message-text {
   word-break: break-word;
+  font-size: 0.95rem;
 }
 
 .message-time {
@@ -1056,3 +1163,42 @@ select {
     scroll-behavior: auto !important;
   }
 }
+
+/* Reconnecting overlay (player error recovery) */
+.reconnecting-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.85);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-4, 1rem);
+  z-index: 1000;
+  backdrop-filter: blur(8px);
+}
+
+.reconnecting-overlay.hidden {
+  display: none;
+}
+
+.reconnecting-spinner {
+  width: 48px;
+  height: 48px;
+  border: 3px solid var(--line, #2a2a2a);
+  border-top-color: var(--brand, #587792);
+  border-radius: 50%;
+  animation: lv-spin 0.8s linear infinite;
+}
+
+@keyframes lv-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+#reconnecting-text {
+  color: var(--ink-0, #ede8e6);
+  font-family: var(--font-body);
+  font-size: 1.125rem;
+}

frontend/vitest.config.ts

@@ -4,5 +4,17 @@ export default defineConfig({
   test: {
     environment: "jsdom",
     include: ["src/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "text-summary"],
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts"],
+      thresholds: {
+        statements: 20,
+        branches: 15,
+        functions: 15,
+        lines: 20,
+      },
+    },
   },
 });

frontend/wrangler.toml

@@ -0,0 +1,6 @@
+name = "linearvoid-frontend"
+compatibility_date = "2025-08-01"
+
+[assets]
+directory = "./dist"
+not_found_handling = "single-page-application"

infrastructure/nginx/nginx.conf

@@ -13,6 +13,14 @@ http {
         '' close;
     }
 
+    map $http_origin $cors_origin {
+        default "";
+        "https://linearvoid.tv"                              $http_origin;
+        "https://www.linearvoid.tv"                          $http_origin;
+        "https://linearvoid-frontend.zwitschi82.workers.dev" $http_origin;
+        "~^https://[a-zA-Z0-9.-]+\.linearvoid\.tv$"          $http_origin;
+    }
+
     server {
         listen 80;
         server_name www.linearvoid.tv;
@@ -85,6 +93,14 @@ http {
         }
 
         location = /api/admin/login {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin $cors_origin;
+                add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
+                add_header Access-Control-Allow-Headers "Content-Type, Authorization";
+                add_header Access-Control-Allow-Credentials true;
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
             set $chat_upstream http://chat:3000;
             proxy_pass $chat_upstream;
             proxy_http_version 1.1;
@@ -93,9 +109,19 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
             proxy_set_header Cookie $http_cookie;
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Credentials true always;
         }
 
         location = /api/admin/logout {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin $cors_origin;
+                add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
+                add_header Access-Control-Allow-Headers "Content-Type, Authorization";
+                add_header Access-Control-Allow-Credentials true;
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
             set $chat_upstream http://chat:3000;
             proxy_pass $chat_upstream;
             proxy_http_version 1.1;
@@ -104,9 +130,19 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
             proxy_set_header Cookie $http_cookie;
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Credentials true always;
         }
 
         location = /api/admin/session {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin $cors_origin;
+                add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
+                add_header Access-Control-Allow-Headers "Content-Type, Authorization";
+                add_header Access-Control-Allow-Credentials true;
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
             set $chat_upstream http://chat:3000;
             proxy_pass $chat_upstream;
             proxy_http_version 1.1;
@@ -115,9 +151,19 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
             proxy_set_header Cookie $http_cookie;
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Credentials true always;
         }
 
         location /api/admin/ {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin $cors_origin;
+                add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
+                add_header Access-Control-Allow-Headers "Content-Type, Authorization";
+                add_header Access-Control-Allow-Credentials true;
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
             auth_request /_admin_auth;
             error_page 401 = @admin_api_unauthorized;
             set $chat_upstream http://chat:3000;
@@ -128,9 +174,19 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
             proxy_set_header Cookie $http_cookie;
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Credentials true always;
         }
 
         location /api/ {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin $cors_origin;
+                add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
+                add_header Access-Control-Allow-Headers "Content-Type, Authorization";
+                add_header Access-Control-Allow-Credentials true;
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
             set $chat_upstream http://chat:3000;
             proxy_pass $chat_upstream;
             proxy_http_version 1.1;
@@ -138,6 +194,8 @@ http {
             proxy_set_header X-Forwarded-Host $host;
             proxy_set_header X-Forwarded-Proto $scheme;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            add_header Access-Control-Allow-Origin $cors_origin always;
+            add_header Access-Control-Allow-Credentials true always;
         }
 
         location = /metrics {

monitoring/grafana/dashboard.json

@@ -1,66 +0,0 @@
-{
-  "title": "Linear Void Monitoring",
-  "panels": [
-    {
-      "title": "Concurrent Viewers",
-      "type": "timeseries",
-      "targets": [{ "expr": "linearvoid_chat_connected_clients" }]
-    },
-    {
-      "title": "Stored Messages",
-      "type": "stat",
-      "targets": [
-        {
-          "expr": "linearvoid_chat_messages_total"
-        }
-      ]
-    },
-    {
-      "title": "Moderation Actions",
-      "type": "timeseries",
-      "targets": [{ "expr": "linearvoid_chat_moderation_actions_total" }]
-    },
-    {
-      "title": "Redis Reachable",
-      "type": "stat",
-      "targets": [{ "expr": "linearvoid_chat_redis_up" }]
-    },
-    {
-      "title": "Admin Sessions",
-      "type": "timeseries",
-      "targets": [{ "expr": "linearvoid_chat_admin_sessions_active" }]
-    },
-    {
-      "title": "Chat Scrape Health",
-      "type": "stat",
-      "targets": [{ "expr": "up{job=\"chat\"}" }]
-    },
-    {
-      "title": "Cache Hit Ratio",
-      "type": "timeseries",
-      "targets": [
-        {
-          "expr": "linearvoid_cache_hit_ratio"
-        }
-      ]
-    },
-    {
-      "title": "Redis Memory Usage",
-      "type": "timeseries",
-      "targets": [
-        {
-          "expr": "linearvoid_chat_redis_memory_usage_ratio"
-        }
-      ]
-    },
-    {
-      "title": "Chat Request Latency p95",
-      "type": "timeseries",
-      "targets": [
-        {
-          "expr": "histogram_quantile(0.95, sum(rate(linearvoid_chat_request_duration_seconds_bucket[5m])) by (le))"
-        }
-      ]
-    }
-  ]
-}

monitoring/grafana/dashboards/nginx.json

@@ -0,0 +1,984 @@
+{
+  "apiVersion": "dashboard.grafana.app/v2",
+  "kind": "Dashboard",
+  "metadata": {
+    "name": "linearvoid-nginx",
+    "namespace": "default",
+    "uid": "d92799b5-4b53-41bb-8fbc-d5cc7aadd858",
+    "resourceVersion": "1786469269844989",
+    "generation": 2,
+    "creationTimestamp": "2026-08-11T17:21:15Z",
+    "labels": {
+      "grafana.app/deprecatedInternalID": "2061233167626240"
+    },
+    "annotations": {
+      "grafana.app/createdBy": "user:efu3jht65vz0gf",
+      "grafana.app/saved-from-ui": "Grafana v13.1.3 (45a27d64b6)",
+      "grafana.app/updatedBy": "user:efu3jht65vz0gf",
+      "grafana.app/updatedTimestamp": "2026-08-11T17:27:49Z"
+    }
+  },
+  "spec": {
+    "annotations": [
+      {
+        "kind": "AnnotationQuery",
+        "spec": {
+          "query": {
+            "kind": "DataQuery",
+            "group": "grafana",
+            "version": "v0",
+            "datasource": {
+              "name": "-- Grafana --"
+            },
+            "spec": {}
+          },
+          "enable": true,
+          "hide": true,
+          "iconColor": "rgba(0, 211, 255, 1)",
+          "name": "Annotations & Alerts",
+          "builtIn": true
+        }
+      }
+    ],
+    "cursorSync": "Off",
+    "editable": true,
+    "elements": {
+      "panel-1": {
+        "kind": "Panel",
+        "spec": {
+          "id": 1,
+          "title": "NGINX Up",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "nginx_up"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "stat",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "colorMode": "value",
+                "graphMode": "area",
+                "justifyMode": "auto",
+                "orientation": "auto",
+                "percentChangeColorMode": "standard",
+                "reduceOptions": {
+                  "calcs": [
+                    "lastNotNull"
+                  ],
+                  "fields": "",
+                  "values": false
+                },
+                "showPercentChange": false,
+                "textMode": "auto",
+                "wideLayout": true
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "mappings": [
+                    {
+                      "type": "value",
+                      "options": {}
+                    },
+                    {
+                      "type": "value",
+                      "options": {}
+                    }
+                  ],
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "red"
+                      },
+                      {
+                        "value": 1,
+                        "color": "green"
+                      }
+                    ]
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-2": {
+        "kind": "Panel",
+        "spec": {
+          "id": 2,
+          "title": "Active Connections",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "nginx_connections_active"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-3": {
+        "kind": "Panel",
+        "spec": {
+          "id": 3,
+          "title": "Connections Reading / Writing / Waiting",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "nginx_connections_reading",
+                        "legendFormat": "reading"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                },
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "nginx_connections_writing",
+                        "legendFormat": "writing"
+                      }
+                    },
+                    "refId": "B",
+                    "hidden": false
+                  }
+                },
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "nginx_connections_waiting",
+                        "legendFormat": "waiting"
+                      }
+                    },
+                    "refId": "C",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-4": {
+        "kind": "Panel",
+        "spec": {
+          "id": 4,
+          "title": "Accepted / Handled Connections",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "nginx_connections_accepted",
+                        "legendFormat": "accepted"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                },
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "nginx_connections_handled",
+                        "legendFormat": "handled"
+                      }
+                    },
+                    "refId": "B",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-5": {
+        "kind": "Panel",
+        "spec": {
+          "id": 5,
+          "title": "HTTP Request Rate",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "rate(nginx_http_requests_total[5m])"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "unit": "reqps",
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-6": {
+        "kind": "Panel",
+        "spec": {
+          "id": 6,
+          "title": "HTTP Requests (total)",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "nginx_http_requests_total"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "stat",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "colorMode": "value",
+                "graphMode": "area",
+                "justifyMode": "auto",
+                "orientation": "auto",
+                "percentChangeColorMode": "standard",
+                "reduceOptions": {
+                  "calcs": [
+                    "lastNotNull"
+                  ],
+                  "fields": "",
+                  "values": false
+                },
+                "showPercentChange": false,
+                "textMode": "auto",
+                "wideLayout": true
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-7": {
+        "kind": "Panel",
+        "spec": {
+          "id": 7,
+          "title": "Connection Drop Ratio",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "(nginx_connections_accepted - nginx_connections_handled) / nginx_connections_accepted"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "unit": "percentunit",
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      }
+    },
+    "layout": {
+      "kind": "GridLayout",
+      "spec": {
+        "items": [
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 0,
+              "y": 0,
+              "width": 12,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-2"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 12,
+              "y": 0,
+              "width": 10,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-3"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 22,
+              "y": 0,
+              "width": 2,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-1"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 0,
+              "y": 5,
+              "width": 12,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-5"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 12,
+              "y": 5,
+              "width": 12,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-6"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 0,
+              "y": 10,
+              "width": 12,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-7"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 12,
+              "y": 10,
+              "width": 12,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-4"
+              }
+            }
+          }
+        ]
+      }
+    },
+    "links": [],
+    "liveNow": false,
+    "preload": false,
+    "tags": [],
+    "timeSettings": {
+      "timezone": "browser",
+      "from": "now-6h",
+      "to": "now",
+      "autoRefresh": "",
+      "autoRefreshIntervals": [
+        "5s",
+        "10s",
+        "30s",
+        "1m",
+        "5m",
+        "15m",
+        "30m",
+        "1h",
+        "2h",
+        "1d"
+      ],
+      "hideTimepicker": false,
+      "fiscalYearStartMonth": 0
+    },
+    "title": "Linearvoid NGINX",
+    "variables": []
+  }
+}

monitoring/grafana/dashboards/playout.json

@@ -0,0 +1,923 @@
+{
+  "apiVersion": "dashboard.grafana.app/v2",
+  "kind": "Dashboard",
+  "metadata": {
+    "name": "linearvoid-playout",
+    "namespace": "default",
+    "uid": "cd256b89-2a57-4202-9c26-d9b6047ca55b",
+    "resourceVersion": "1786469434829007",
+    "generation": 2,
+    "creationTimestamp": "2026-08-11T17:17:57Z",
+    "labels": {
+      "grafana.app/deprecatedInternalID": "2060404050194432"
+    },
+    "annotations": {
+      "grafana.app/createdBy": "user:efu3jht65vz0gf",
+      "grafana.app/saved-from-ui": "Grafana v13.1.3 (45a27d64b6)",
+      "grafana.app/updatedBy": "user:efu3jht65vz0gf",
+      "grafana.app/updatedTimestamp": "2026-08-11T17:30:34Z"
+    }
+  },
+  "spec": {
+    "annotations": [
+      {
+        "kind": "AnnotationQuery",
+        "spec": {
+          "query": {
+            "kind": "DataQuery",
+            "group": "grafana",
+            "version": "v0",
+            "datasource": {
+              "name": "-- Grafana --"
+            },
+            "spec": {}
+          },
+          "enable": true,
+          "hide": true,
+          "iconColor": "rgba(0, 211, 255, 1)",
+          "name": "Annotations & Alerts",
+          "builtIn": true
+        }
+      }
+    ],
+    "cursorSync": "Off",
+    "editable": true,
+    "elements": {
+      "panel-1": {
+        "kind": "Panel",
+        "spec": {
+          "id": 1,
+          "title": "Playout Service Up",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "up{job=\"playout\"}"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "stat",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "colorMode": "value",
+                "graphMode": "area",
+                "justifyMode": "auto",
+                "orientation": "auto",
+                "percentChangeColorMode": "standard",
+                "reduceOptions": {
+                  "calcs": [
+                    "lastNotNull"
+                  ],
+                  "fields": "",
+                  "values": false
+                },
+                "showPercentChange": false,
+                "textMode": "auto",
+                "wideLayout": true
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "mappings": [
+                    {
+                      "type": "value",
+                      "options": {}
+                    },
+                    {
+                      "type": "value",
+                      "options": {}
+                    }
+                  ],
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "red"
+                      },
+                      {
+                        "value": 1,
+                        "color": "green"
+                      }
+                    ]
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-2": {
+        "kind": "Panel",
+        "spec": {
+          "id": 2,
+          "title": "Playout Mode",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "linearvoid_playout_mode"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "stat",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "colorMode": "value",
+                "graphMode": "area",
+                "justifyMode": "auto",
+                "orientation": "auto",
+                "percentChangeColorMode": "standard",
+                "reduceOptions": {
+                  "calcs": [
+                    "lastNotNull"
+                  ],
+                  "fields": "",
+                  "values": false
+                },
+                "showPercentChange": false,
+                "textMode": "auto",
+                "wideLayout": true
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "mappings": [
+                    {
+                      "type": "value",
+                      "options": {}
+                    },
+                    {
+                      "type": "value",
+                      "options": {}
+                    },
+                    {
+                      "type": "value",
+                      "options": {}
+                    }
+                  ],
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 1,
+                        "color": "orange"
+                      },
+                      {
+                        "value": 2,
+                        "color": "red"
+                      }
+                    ]
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-3": {
+        "kind": "Panel",
+        "spec": {
+          "id": 3,
+          "title": "FFmpeg Restarts (total)",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "linearvoid_playout_restarts_total"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "stat",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "colorMode": "value",
+                "graphMode": "area",
+                "justifyMode": "auto",
+                "orientation": "auto",
+                "percentChangeColorMode": "standard",
+                "reduceOptions": {
+                  "calcs": [
+                    "lastNotNull"
+                  ],
+                  "fields": "",
+                  "values": false
+                },
+                "showPercentChange": false,
+                "textMode": "auto",
+                "wideLayout": true
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-4": {
+        "kind": "Panel",
+        "spec": {
+          "id": 4,
+          "title": "FFmpeg Restart Rate",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "rate(linearvoid_playout_restarts_total[5m])"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "unit": "ops/s",
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-5": {
+        "kind": "Panel",
+        "spec": {
+          "id": 5,
+          "title": "Playout Mode Over Time",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "linearvoid_playout_mode"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "unit": "none",
+                  "mappings": [
+                    {
+                      "type": "value",
+                      "options": {}
+                    },
+                    {
+                      "type": "value",
+                      "options": {}
+                    },
+                    {
+                      "type": "value",
+                      "options": {}
+                    }
+                  ],
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 1,
+                        "color": "orange"
+                      },
+                      {
+                        "value": 2,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-6": {
+        "kind": "Panel",
+        "spec": {
+          "id": 6,
+          "title": "FFmpeg Restarts (cumulative)",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "linearvoid_playout_restarts_total"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      },
+      "panel-7": {
+        "kind": "Panel",
+        "spec": {
+          "id": 7,
+          "title": "Scrape Duration (playout)",
+          "description": "",
+          "links": [],
+          "data": {
+            "kind": "QueryGroup",
+            "spec": {
+              "queries": [
+                {
+                  "kind": "PanelQuery",
+                  "spec": {
+                    "query": {
+                      "kind": "DataQuery",
+                      "group": "prometheus",
+                      "version": "v0",
+                      "datasource": {
+                        "name": "PBFA97CFB590B2093"
+                      },
+                      "spec": {
+                        "expr": "scrape_duration_seconds{job=\"playout\"}"
+                      }
+                    },
+                    "refId": "A",
+                    "hidden": false
+                  }
+                }
+              ],
+              "transformations": [],
+              "queryOptions": {}
+            }
+          },
+          "vizConfig": {
+            "kind": "VizConfig",
+            "group": "timeseries",
+            "version": "13.1.3",
+            "spec": {
+              "options": {
+                "annotations": {
+                  "clustering": -1,
+                  "multiLane": false
+                },
+                "legend": {
+                  "calcs": [],
+                  "displayMode": "list",
+                  "enableFacetedFilter": false,
+                  "overflow": "ellipsis",
+                  "placement": "bottom",
+                  "showLegend": true
+                },
+                "tooltip": {
+                  "hideZeros": false,
+                  "mode": "single",
+                  "sort": "none"
+                }
+              },
+              "fieldConfig": {
+                "defaults": {
+                  "unit": "s",
+                  "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                      {
+                        "value": 0,
+                        "color": "green"
+                      },
+                      {
+                        "value": 80,
+                        "color": "red"
+                      }
+                    ]
+                  },
+                  "color": {
+                    "mode": "palette-classic"
+                  },
+                  "custom": {
+                    "axisBorderShow": false,
+                    "axisCenteredZero": false,
+                    "axisColorMode": "text",
+                    "axisLabel": "",
+                    "axisPlacement": "auto",
+                    "barAlignment": 0,
+                    "barWidthFactor": 0.6,
+                    "drawStyle": "line",
+                    "fillOpacity": 0,
+                    "gradientMode": "none",
+                    "hideFrom": {
+                      "legend": false,
+                      "tooltip": false,
+                      "viz": false
+                    },
+                    "insertNulls": false,
+                    "lineInterpolation": "linear",
+                    "lineWidth": 1,
+                    "pointSize": 5,
+                    "scaleDistribution": {
+                      "type": "linear"
+                    },
+                    "showPoints": "auto",
+                    "showValues": false,
+                    "spanNulls": false,
+                    "stacking": {
+                      "group": "A",
+                      "mode": "none"
+                    },
+                    "thresholdsStyle": {
+                      "mode": "off"
+                    }
+                  }
+                },
+                "overrides": []
+              }
+            }
+          }
+        }
+      }
+    },
+    "layout": {
+      "kind": "GridLayout",
+      "spec": {
+        "items": [
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 0,
+              "y": 0,
+              "width": 4,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-1"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 4,
+              "y": 0,
+              "width": 4,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-2"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 8,
+              "y": 0,
+              "width": 4,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-3"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 12,
+              "y": 0,
+              "width": 12,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-5"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 0,
+              "y": 5,
+              "width": 12,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-4"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 12,
+              "y": 5,
+              "width": 12,
+              "height": 5,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-6"
+              }
+            }
+          },
+          {
+            "kind": "GridLayoutItem",
+            "spec": {
+              "x": 0,
+              "y": 10,
+              "width": 24,
+              "height": 4,
+              "element": {
+                "kind": "ElementReference",
+                "name": "panel-7"
+              }
+            }
+          }
+        ]
+      }
+    },
+    "links": [],
+    "liveNow": false,
+    "preload": false,
+    "tags": [],
+    "timeSettings": {
+      "timezone": "browser",
+      "from": "now-6h",
+      "to": "now",
+      "autoRefresh": "",
+      "autoRefreshIntervals": [
+        "5s",
+        "10s",
+        "30s",
+        "1m",
+        "5m",
+        "15m",
+        "30m",
+        "1h",
+        "2h",
+        "1d"
+      ],
+      "hideTimepicker": false,
+      "fiscalYearStartMonth": 0
+    },
+    "title": "Linearvoid Playout",
+    "variables": []
+  }
+}

scripts/loadtest/README.md

@@ -1,6 +1,6 @@
 # Load Test Scaffolding
 
-These files back the scaling/performance playbook.
+These files back the [scaling/performance playbook](../../docs/operations/scaling-performance-playbook.md).
 
 ## WebSocket chat
 

scripts/validate-edge-cache.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+# Edge cache hit/miss validation (Phase 4 — STREAMING.md cache contract)
+# Verifies: .m4s segments go MISS→HIT, init.mp4 is cached, .m3u8 refreshes quickly
+# Usage: ./scripts/validate-edge-cache.sh [base_url]
+#   Default base_url: https://media.linearvoid.tv
+
+set -euo pipefail
+
+BASE_URL="${1:-https://media.linearvoid.tv}"
+TIMEOUT=10
+FAILURES=0
+PASSES=0
+
+green() { echo -e "\033[32m$1\033[0m"; }
+red() { echo -e "\033[31m$1\033[0m"; }
+
+pass() { PASSES=$((PASSES + 1)); green "  ✓ PASS: $1"; }
+fail() { FAILURES=$((FAILURES + 1)); red "  ✗ FAIL: $1"; }
+
+# Fetch a header from a URL
+fetch_header() {
+    local url="$1" header="$2"
+    curl -sI --connect-timeout "$TIMEOUT" --max-time "$TIMEOUT" "$url" 2>/dev/null | \
+        grep -i "^${header}:" | sed 's/.*: //' | tr -d '\r' || echo ""
+}
+
+echo "=== Edge Cache Validation ==="
+echo "Target: $BASE_URL"
+echo ""
+
+# 1. Get current playlist manifest and extract a segment name
+echo "--- Test 1: Manifest freshness ---"
+MANIFEST_URL="$BASE_URL/hls/playlist.m3u8"
+MANIFEST=$(curl -s --connect-timeout "$TIMEOUT" --max-time "$TIMEOUT" "$MANIFEST_URL" 2>/dev/null || echo "")
+
+if [[ -z "$MANIFEST" ]]; then
+    fail "Manifest is empty or unreachable"
+else
+    if echo "$MANIFEST" | grep -q "#EXTM3U"; then
+        pass "Manifest is valid M3U8"
+    else
+        fail "Manifest missing #EXTM3U header"
+    fi
+fi
+
+SEGMENT=$(echo "$MANIFEST" | grep "\.m4s" | tail -1 | tr -d '\r')
+if [[ -z "$SEGMENT" ]]; then
+    fail "No .m4s segment found in manifest"
+else
+    pass "Found segment: $SEGMENT"
+fi
+
+# 2. Test manifest Cache-Control
+MANIFEST_CC=$(fetch_header "$MANIFEST_URL" "Cache-Control")
+echo ""
+echo "--- Test 2: Manifest Cache-Control ---"
+if echo "$MANIFEST_CC" | grep -q "must-revalidate"; then
+    pass "Manifest has must-revalidate ($MANIFEST_CC)"
+else
+    fail "Manifest missing must-revalidate ($MANIFEST_CC)"
+fi
+if echo "$MANIFEST_CC" | grep -q "max-age"; then
+    pass "Manifest has max-age ($MANIFEST_CC)"
+else
+    fail "Manifest missing max-age ($MANIFEST_CC)"
+fi
+
+# 3. Test segment cache (MISS → HIT)
+if [[ -n "$SEGMENT" ]]; then
+    SEGMENT_URL="$BASE_URL/hls/$SEGMENT"
+    echo ""
+    echo "--- Test 3: Segment cache MISS→HIT ---"
+    
+    FIRST_STATUS=$(fetch_header "$SEGMENT_URL" "CF-Cache-Status")
+    echo "  First request: CF-Cache-Status=$FIRST_STATUS"
+    
+    sleep 1
+    
+    SECOND_STATUS=$(fetch_header "$SEGMENT_URL" "CF-Cache-Status")
+    echo "  Second request: CF-Cache-Status=$SECOND_STATUS"
+    
+    if [[ "$SECOND_STATUS" == "HIT" ]]; then
+        pass "Segment cache HIT on second request (was $FIRST_STATUS)"
+    elif [[ "$FIRST_STATUS" == "HIT" ]]; then
+        pass "Segment already cached (HIT on first request)"
+    else
+        fail "Segment not cached: first=$FIRST_STATUS, second=$SECOND_STATUS"
+    fi
+fi
+
+# 4. Test segment Cache-Control (immutable)
+if [[ -n "$SEGMENT" ]]; then
+    echo ""
+    echo "--- Test 4: Segment immutable cache ---"
+    SEGMENT_CC=$(fetch_header "$SEGMENT_URL" "Cache-Control")
+    if echo "$SEGMENT_CC" | grep -q "immutable"; then
+        pass "Segment has immutable ($SEGMENT_CC)"
+    else
+        fail "Segment missing immutable ($SEGMENT_CC)"
+    fi
+    if echo "$SEGMENT_CC" | grep -q "max-age=31536000"; then
+        pass "Segment has 1-year max-age ($SEGMENT_CC)"
+    else
+        fail "Segment missing 1-year max-age ($SEGMENT_CC)"
+    fi
+fi
+
+# 5. Test init.mp4 cache
+echo ""
+echo "--- Test 5: Init segment cache ---"
+INIT_URL="$BASE_URL/hls/init.mp4"
+INIT_STATUS=$(fetch_header "$INIT_URL" "CF-Cache-Status")
+INIT_CC=$(fetch_header "$INIT_URL" "Cache-Control")
+if [[ "$INIT_STATUS" == "HIT" ]]; then
+    pass "Init segment cached (CF-Cache-Status=$INIT_STATUS, CC=$INIT_CC)"
+else
+    fail "Init segment not cached: $INIT_STATUS"
+fi
+
+# 6. Test manifest refresh (should NOT be cached long-term)
+echo ""
+echo "--- Test 6: Manifest refresh rate ---"
+MANIFEST_CF=$(fetch_header "$MANIFEST_URL" "CF-Cache-Status")
+echo "  Manifest CF-Cache-Status: $MANIFEST_CF"
+# DYNAMIC or BYPASS is correct for live manifests. HIT with long TTL is wrong.
+if [[ "$MANIFEST_CF" == "DYNAMIC" ]] || [[ "$MANIFEST_CF" == "BYPASS" ]] || [[ "$MANIFEST_CF" == "MISS" ]] || [[ "$MANIFEST_CF" == "REVALIDATED" ]]; then
+    pass "Manifest not long-term cached ($MANIFEST_CF)"
+elif [[ "$MANIFEST_CF" == "HIT" ]]; then
+    fail "Manifest is HIT — may be stale (check TTL)"
+else
+    pass "Manifest status: $MANIFEST_CF (no HIT = acceptable)"
+fi
+
+# Summary
+echo ""
+echo "=== Results: $PASSES passed, $FAILURES failed ==="
+
+if [[ $FAILURES -gt 0 ]]; then
+    exit 1
+fi
+exit 0