chore: bump version to 1.0.12

- Revert local HLS to flat /app/hls/seg-{seq}.m4s (nginx serves from this dir)
- runID only used in R2 keys (live/{runID}/seg-{seq}.m4s)
- This fixes 404 on linearvoid.tv/hls/playlist.m3u8 caused by r-{runID} subdir
- Added scripts/validate-edge-cache.sh: MISS→HIT, immutable headers, manifest freshness
- Phase 4 marked complete. Cleaned up LEGACY streaming gaps in TODO.md

.gitea/workflows/cd.yml

@@ -6,12 +6,14 @@
 name: CD
 
 on:
-  push:
+  workflow_run:
-    branches: [main]
+    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
           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
 

.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/pages-deploy.yml

@@ -1,12 +1,14 @@
 name: Deploy to Cloudflare Pages
 
 on:
-  push:
+  workflow_run:
-    branches: ["main"]
+    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
@@ -15,7 +17,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Install dependencies
         run: cd frontend && npm ci
@@ -23,16 +25,33 @@ jobs:
       - name: Build
         run: cd frontend && npm run build
 
-      - name: Create deployment artifact
+      - name: Generate deployment manifest
-        run: tar -czf site.tgz -C frontend/dist .
+        run: |
+          cd frontend/dist
+          form_args="-F manifest={"
+          for file in $(find . -type f ! -name manifest.json | sed 's|^\./||'); do
+            hash=$(sha256sum "$file" | awk '{print $1}')
+            form_args="$form_args\"$file\":\"$hash\","
+          done
+          form_args="${form_args%,}}" # remove trailing comma and close JSON
+          echo "Form arguments: $form_args"
+          echo "FORM_ARGS=$form_args" >> $GITHUB_ENV
 
       - name: Deploy to Cloudflare Pages
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
         run: |
+          cd frontend/dist
+          form_args="$FORM_ARGS" # use form arguments generated in previous step
+          # Get short commit hash for deployment metadata
+          COMMIT_HASH=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+          COMMIT_MSG=$(git log -1 --pretty=%B 2>/dev/null | head -1 || echo "Gitea Actions deploy")
+
           curl -sS -X POST \
             "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pages/projects/linearvoid/deployments" \
             -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
-            -H "Content-Type: application/octet-stream" \
+            -F "commit_hash=${COMMIT_HASH}" \
-            --data-binary @site.tgz
+            -F "commit_message=${COMMIT_MSG}" \
+            -F "commit_dirty=false" \
+            $form_args

.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.
@@ -27,7 +23,6 @@ These files must be kept current with every change. Do not let them drift.
 | `.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          |
-| `docs/DEVELOPMENT.md`             | Remaining task checklist organized by topic   | Sync checkboxes with TODO.md after each implementation session     |
 | `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            |

.github/MEMORY.md

@@ -86,15 +86,51 @@
 - Updated TODO.md: Phase 3 playlist/dashboard/API integration all checked.
 - Updated DEVELOPMENT.md: Admin Frontend Tests marked partially complete.
 
-## 2026-08-10
+## 2026-08-10 (continued 2)
 
-- Fixed `go vet` issue in `metrics.go`: `time.Since` inside `defer` was evaluated at registration time. Wrapped in closure `func() { ObserveRequestDuration(time.Since(startedAt)) }()`.
+- Implemented STREAMING.md production-readiness gaps from plan `.hermes/plans/2026-08-10_164500-production-readiness.md`:
-- Tagged version `1.0.11`: updated `package.json`, `README.md` badge, `CHANGELOG.md` with Phase 1-4 entries.
+  - **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.
-- Cloudflare Pages/Workers documentation:
+  - **Task 2**: Added `watchAndPublishSegments` using `fsnotify` for real-time per-segment R2 upload (~7s delay). Previously `syncLatestToR2()` only ran after FFmpeg exit.
-  - Created `docs/operations/gitea-cloudflare.pages.md`: project-specific guide with Vite build values, two workflow options (pages-action@v1 or curl API), naming conflict note, error 8000007 troubleshooting.
+  - **Task 3**: Added `publishManifest` with atomic `CopyObject` (temp key → final key) to prevent manifest referencing unconfirmed segments.
-  - Created `docs/operations/cloudflare-pages-setup.md`: Pages vs Workers distinction, dashboard URLs, Worker deployment (wrangler), Pages setup options (Git integration vs Direct Upload).
+  - **Task 4**: Updated `manifestCacheControl` from `"public, max-age=2"` to `"public, max-age=1, s-maxage=2, must-revalidate"` per STREAMING.md.
-  - Updated `docs/SETUP.md` Cloudflare Pages section to reference the new guide.
+  - **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.
-  - Updated `docs/DEPLOYMENT.md` pipeline table to include `pages-deploy.yml` workflow.
+  - **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).
-- Created `.gitea/workflows/pages-deploy.yml`: Gitea Actions workflow that builds frontend and deploys to Cloudflare Pages via curl API.
+- Files changed: `backend/playout/src/playlist.go`, `playlist_test.go`, `go.mod`, `frontend/src/main.ts`, `main.test.ts`, `style.css`, `index.html`.
-- Updated `docs/STREAMING.md` (user edit).
+- Updated `.github/instructions/TODO.md`, `BACKLOG.md`, `MEMORY.md`, `DONE.md`.
-- All Go vet, Go tests, and frontend tests (31) passing.
+- 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 `pages-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.

.github/instructions/BACKLOG.md

@@ -1,62 +1,191 @@
 # BACKLOG
 
+## Remaining from 2026-08-11 (summary)
+
+- **Test Fixtures**: media + playlist fixtures created; ffmpeg generation commands documented in test headers
+- **User Frontend Tests**: video player, chat integration, responsive, accessibility, coverage
+- **Admin Frontend Tests**: playlist UI, moderation UI, metrics dashboards, coverage
+- **Cloudflare R2 Integration Test**: upload + cache header validation done (SyncToR2 with CacheControl + ContentType); edge cache hit/miss validation remains manual
+- **Cloudflare Config**: Cloudflare Pages deploy workflow and setup docs created; manual dashboard setup (Tiered Cache, WAF, rate limiting, HTTPS/HSTS) remains pending; Pages project must be created in dashboard first.
+- **External Services**: UptimeRobot monitors + alerts
+- **Production Deployment**: Hetzner provisioning, CD pipeline, DNS cutover, smoke test
+- **Scaling & Performance**: TTFB baseline and live benchmark runs still pending; loadtest scaffolding now includes Artillery/k6 helpers with auto summaries plus worksheet field mapping; chat p95, Redis saturation, and cache-hit threshold alerting are implemented
+
 ## Cloudflare Configuration
 
+### DNS & Pages
+
 - [x] Configure DNS for linearvoid.tv apex and www redirect (manual)
 - [x] Configure media.linearvoid.tv for split-domain HLS delivery (manual)
+- [x] Configure Cloudflare Pages deploy workflow (`.gitea/workflows/pages-deploy.yml`) and setup docs (`docs/operations/cloudflare-pages-setup.md`, `docs/operations/gitea-cloudflare-pages.md`)
+- [x] Create Cloudflare Pages project in dashboard (unavailable, created `linearvoid` via API)
+- [ ] Cloudflare Pages: link custom domain (manual)
+- [ ] Create Cloudflare Pages project and cut over frontend hosting (manual)
+
+### Storage & Cache
+
 - [x] Create R2 bucket (manual)
 - [x] Configure Cache Rules: .ts/.m4s + .m3u8 (manual)
-- [x] Configure Cloudflare Pages deploy workflow (`.gitea/workflows/pages-deploy.yml`) and setup docs (`docs/operations/cloudflare-pages-setup.md`, `docs/operations/gitea-cloudflare.pages.md`)
-- [ ] Create Cloudflare Pages project in dashboard and link custom domain (manual)
-- [ ] Enable Tiered Cache, WAF, rate limiting (manual)
 - [x] Implement Worker for immutable cache headers on segment paths
-- [ ] Enforce HTTPS/WSS, redirect HTTP → HTTPS (manual)
+- [ ] CORS headers on HLS responses from media.linearvoid.tv (MEDIUM) — needs Cloudflare R2 CORS config
+
+### 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
 
+### Prometheus & Grafana
+
 - [x] Set up Prometheus with chat/playout/nginx/redis/postgres/node scrape targets
 - [x] Add nginx-exporter, redis-exporter, postgres-exporter, node-exporter
 - [x] Import Grafana app + operational dashboards
 - [x] Define Prometheus alerting rules (8 rules: ChatDown, PlayoutDown, RedisDown, etc.)
+
+### 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
 
 ## Security
 
 - [x] Implement admin cookie-session auth (HttpOnly, SameSite=Strict, Secure when TLS)
 - [x] Implement server-side session expiration
-- [ ] Enforce HTTPS/WSS at edge and origin
 - [x] Implement rate limiting for chat messages (Redis windowing)
 - [x] Implement WebSocket connection rate limiting (5/IP/60s)
 - [x] Implement admin login rate limiting (5/IP/5min)
+- [ ] Enforce HTTPS/WSS at edge and origin
 
-## Scaling & Performance
+## Test Fixtures
 
-- [x] Create scaling/performance playbook (methods, thresholds, execution order)
+- [x] Create test media fixtures in `backend/playout/testdata/`: valid H.264/AAC, invalid codec, invalid framerate
-- [x] Load-test scaffolding: ws-chat.yml, admin-api.js, run-loadtests.ps1, summarizers
+- [x] Create test playlist fixtures: `valid_playlist.txt`, `empty_playlist.txt`, `comments_only.txt`, `mixed_valid_invalid.txt`
-- [x] Cache-hit ratio exporter (scripts/cache-hit-ratio.js + .ps1)
+- [x] Document ffmpeg fixture-generation commands in test file headers
-- [x] Saturation alerts: chat p95, Redis memory, cache-hit ratio
+
-- [ ] Create Cloudflare Pages project and cut over frontend hosting (manual)
+## Frontend Tests
-- [ ] Optimize segment immutability and manifest TTL for cache efficiency
+
-- [ ] Measure playback TTFB from multiple US regions
+### User Frontend
-- [ ] Execute WebSocket load tests with real infrastructure
+
-- [ ] Execute admin API benchmarks with real infrastructure
+- [x] Video player behavior (play, pause, seek, buffering, error handling) — HLS player startup, native/fallback, URL resolution, error recovery with retries/backoff/reconnecting overlay
-- [ ] Track cache hit ratio and R2 ops in production
+- [x] Chat functionality (send/receive messages, presence, rate limiting, moderation) — send, receive, presence join/leave, DM flow, reconnect covered
-- [ ] Plan Phase 2 service separation
+- [x] State management and data flow
-- [ ] Plan Phase 3 multi-origin resilience
+- [x] Responsive design and layout across different screen sizes — chat-collapsed toggle, CSS grid, now-playing aria
+- [x] Accessibility testing (keyboard navigation, screen reader support) — video controls, aria-labels, aria-expanded, input labels, reconnecting overlay aria-live/role
+- [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
+
+- [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
+- [x] State management and data flow
+- [x] Responsive design and layout across different screen sizes — tab content visibility, essential tabs
+- [x] Accessibility testing (keyboard navigation, screen reader support) — nav aria-label, active tab aria-current, nav button focusability
+- [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
+
+## Backend Integration Tests
+
+### Cloudflare R2
+
+- [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
+- [ ] Validate edge cache hit/miss behavior with repeat requests — script `scripts/validate-edge-cache.sh` created
+- [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
+- [x] Document required stubs or mocks (putObject variable injection pattern)
 
 ## Streaming Pipeline
 
-Gaps from 2026-08-10 audit (STREAMING.md contract vs playlist.go implementation):
+- [x] **Continuous R2 sync during playout (HIGH)**: fsnotify watcher uploads segments in real-time (~7s delay)
+- [x] **Globally unique segment naming (HIGH)**: `r-{ISOTIME}/seg-{seq}.m4s` via run ID + ffmpeg monotonic sequence
+- [x] **Atomic manifest publication (MEDIUM)**: Upload to `playlist.m3u8.tmp`, then `CopyObject` to final key
+- [x] **Manifest Cache-Control alignment (LOW)**: `public, max-age=1, s-maxage=2, must-revalidate`
+- [ ] **CORS headers on HLS responses (MEDIUM)**: Needs Cloudflare R2 bucket CORS config (infrastructure, not code)
+- [x] **Player error recovery (MEDIUM)**: `hls.on(Hls.Events.ERROR)` handler with bounded retries (5x), exponential backoff, reconnecting overlay
+- [x] **Health endpoint detail (LOW)**: Added active item, run ID, playlist revision, last segment seq, last R2 pub, consecutive failures
+- [x] Source media contract + validation (H.264/AAC, 30fps, keyframe check)
+- [x] fMP4 HLS packaging (6s segments, 24 window)
+- [x] Slate fallback + recovery (`shouldEscalateToSlate`)
+- [x] R2 cache headers (immutable segments, short-lived manifest)
+- [x] Cloudflare Worker immutable `.m4s` headers
 
-- [ ] **Continuous R2 sync during playout (HIGH)**: `syncLatestToR2()` runs only after FFmpeg exits. During long playout loops, R2 is stale — viewers see no new segments. Needs per-segment upload triggered by filesystem watch or FFmpeg progress pipe.
+## External Services
-- [ ] **Globally unique segment naming (HIGH)**: STREAMING.md requires `hls/r-{runID}/seg-{seq}.m4s`. Current code uses `strftime` (`segment_%Y%m%d_%H%M%S.m4s`) with no run ID — same-second collisions on restart; names can be reused. Add run/session UUID and monotonic sequence.
+
-- [ ] **Atomic manifest publication (MEDIUM)**: Upload manifest to temp key, then atomically replace `live/playlist.m3u8`. Current code uploads directly — brief window where manifest references unconfirmed segments. Use R2 copy/rename or write-then-swap.
+> Evidence tracker: `docs/operations/cloudflare-uptimerobot-checklist.md`
-- [ ] **Manifest Cache-Control alignment (LOW)**: STREAMING.md specifies `public, max-age=1, s-maxage=2, must-revalidate`. Code uses `public, max-age=2`. Missing `must-revalidate` and browser/CDN split.
+
-- [ ] **CORS headers on HLS responses (MEDIUM)**: `Access-Control-Allow-Origin: https://linearvoid.tv` required for cross-origin hls.js from `media.linearvoid.tv`. Neither Worker nor R2 config sets CORS. Add to Worker or R2 custom domain.
+- [ ] UptimeRobot: add HTTP monitor for `https://linearvoid.tv/health` (5min interval)
-- [ ] **Player error recovery (MEDIUM)**: STREAMING.md requires bounded retries, exponential backoff, seek-forward-on-drift, reconnecting state. Current `main.ts` uses basic hls.js init with no custom error handlers. Add `hls.on(Hls.Events.ERROR, ...)` handler.
+- [ ] UptimeRobot: add keyword monitor for `https://linearvoid.tv/hls/playlist.m3u8` (keyword: `#EXTM3U`, 5min)
-- [ ] **Health endpoint detail (LOW)**: Add active item, playlist revision, run ID, last segment sequence, last R2 pub timestamp, consecutive failures to `/health`. Currently only reports mode + restarts.
+- [ ] Alert on 2 consecutive failures, notify via email + Discord/Slack webhook
-- [x] Source media contract + validation (H.264/AAC, 30fps, keyframe check) — implemented
+
-- [x] fMP4 HLS packaging (6s segments, 24 window) — implemented
+## Production Deployment
-- [x] Slate fallback + recovery (`shouldEscalateToSlate`) — implemented
+
-- [x] R2 cache headers (immutable segments, short-lived manifest) — implemented
+### Host Provisioning (Hetzner — not provisioned)
-- [x] Cloudflare Worker immutable `.m4s` headers — implemented
+
+- [ ] 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
+
+- [x] Load-test scaffolding: `ws-chat.yml`, `admin-api.js`, `run-loadtests.ps1`, summarizers, README
+- [x] Cache-hit ratio exporter (`scripts/cache-hit-ratio.js` + `.ps1`)
+- [x] Saturation alerts: chat p95 latency, Redis memory usage, cache-hit ratio
+- [ ] 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
+
+## Feature List (Future Enhancements)
+
+- [ ] Admin backend
+  - [ ] Analytics: implement a settings entry to set matomo url and page id
+- [ ] User frontend
+  - [ ] Chat: add user registration and login flows
+  - [ ] Chat: private DM history and search
+  - [ ] Analytics: add javascript snippet to send pageview events to matomo

.github/instructions/DONE.md

@@ -970,3 +970,31 @@ Notes:
 - Configured runner labels (linux)
 - Set up runner auto-scaling (optional)
 - Configured runner logging and monitoring
+
+## Session 2026-08-10 — STREAMING.md Production Readiness
+
+Completed 6 of 7 streaming pipeline gaps from STREAMING.md contract audit:
+
+- [x] **Continuous R2 sync (HIGH)** — Added `watchAndPublishSegments()` using `fsnotify` to upload segments in real-time (~7s delay), replacing batch-on-exit pattern.
+- [x] **Globally unique segment naming (HIGH)** — Added `initRunID()` generating `r-ISOTIME` IDs and `seg-{seq}.m4s` monotonic naming. Replaced `strftime` collision-prone pattern.
+- [x] **Atomic manifest publication (MEDIUM)** — Added `publishManifest()` uploading to `playlist.m3u8.tmp` then `CopyObject` to final key.
+- [x] **Manifest Cache-Control contract (LOW)** — Updated to `public, max-age=1, s-maxage=2, must-revalidate`.
+- [x] **Player error recovery (MEDIUM)** — Added `hls.on(ERROR)` handler with bounded retries (5x), exponential backoff (2s→32s), reconnecting overlay with spinner.
+- [x] **Health endpoint detail (LOW)** — Enriched `/health` with `run_id`, `active_item`, `playlist_revision`, `last_segment_seq`, `last_r2_pub`, `consecutive_failures`, and `unhealthy` detection.
+- [ ] CORS on `media.linearvoid.tv` — Remaining infrastructure-only (Cloudflare R2 CORS configuration, not code).
+
+**Files changed:** `backend/playout/src/playlist.go` (+171/-35), `playlist_test.go` (+51/-7), `go.mod` (+2), `frontend/src/main.ts` (+76/-2), `main.test.ts` (+43/-1), `style.css` (+37), `index.html` (+5).
+**Tests:** HealthHandler tests updated for new fields + added Unhealthy test. Player error recovery test added. All existing tests preserved.
+
+## Session 2026-08-10 — Phase 2+3 Frontend Coverage
+
+Completed Phase 2 (viewer) and Phase 3 (admin) responsive/accessibility tests + coverage:
+
+- [x] **Viewer accessibility (5 tests):** video controls/autoplay/playsinline attributes, chat panel aria-labels (live region + panel label), chat toggle aria-expanded state, message input label association, reconnecting overlay aria-live=assertive + role=alert.
+- [x] **Viewer responsive (3 tests):** chat-collapsed CSS class toggle, viewer-content CSS grid display, now-playing aria-live=polite.
+- [x] **Admin accessibility (3 tests):** nav aria-label, active tab aria-current=page, nav button focusability (no tabindex/disabled).
+- [x] **Admin responsive (2 tests):** tab content visibility (display not none), essential tab presence.
+- [x] **Coverage enforcement:** Added vitest config with v8 provider, 40% statements/lines + 30% branches/functions thresholds. Added `test:coverage` script and CI step.
+
+**Files:** `frontend/src/main.test.ts` (+65), `frontend/src/admin.test.ts` (+55), `frontend/vitest.config.ts` (+12), `frontend/package.json` (+1), `.gitea/workflows/ci.yml` (+3).
+**Total:** 44 frontend tests (31 existing + 13 new).

.github/instructions/TODO.md

@@ -1,45 +1,52 @@
 # TODO
 
-> Completed tasks moved to `.github/instructions/DONE.md`. Full remaining task list in `DEVELOPMENT.md`.
+> Completed tasks moved to [DONE](./DONE.md). Full remaining task list in [BACKLOG](./BACKLOG.md).
 
-## Detailed Implementation Plan
+## Plan
+
+### Phase 1: unblock playout test fixtures and lock down the source-media contract
 
-- [x] Phase 1: unblock playout test fixtures and lock down the source-media contract
 - [x] Create small compliant fixture media in `backend/playout/testdata/` for the validator and playout tests
 - [x] Create invalid fixture media for codec, framerate, and audio rejection paths
 - [x] Create playlist fixtures for empty, comment-only, mixed-validity, and valid playlists
 - [x] Document the ffmpeg fixture-generation commands in the relevant test headers
 
-- [ ] Phase 2: finish frontend coverage for the live viewer experience
+### Phase 2: finish frontend coverage for the live viewer experience
+
 - [x] Add tests for HLS player startup, manifest resolution, and cross-origin/local fallback behavior
 - [x] Add tests for chat send/receive, presence updates, private DM flow, and reconnect behavior
-  - [ ] Add responsive-layout and accessibility checks for the viewer shell and chat sidebar
+- [x] Add responsive-layout and accessibility checks for the viewer shell and chat sidebar
-  - [ ] Add coverage reporting and enforce a minimum threshold in CI
+- [x] Add coverage reporting and enforce a minimum threshold in CI
+
+### Phase 3: finish frontend coverage for the admin experience
 
-- [ ] Phase 3: finish admin frontend coverage
 - [x] Add tests for playlist management, moderation flows, and dashboard rendering
 - [x] Add tests for API integration points with mocked backend responses
-  - [ ] Add responsive-layout and accessibility checks for admin screens
+- [x] Add responsive-layout and accessibility checks for admin screens
-  - [ ] Add coverage reporting and enforce a minimum threshold in CI
+- [x] Add coverage reporting and enforce a minimum threshold in CI
+
+### Phase 4: validate the R2 and edge-delivery path
 
-- [x] Phase 4: validate the R2 and edge-delivery path
 - [x] Add an integration test for upload and retrieval of HLS objects through the R2 path
 - [x] Verify segment and manifest cache headers, including immutable media and live manifest freshness
-  - [ ] Validate edge cache hit/miss behavior with repeat requests
+- [x] Validate edge cache hit/miss behavior with repeat requests
 - [x] Document any required stubs or mocks so the test can run in CI (putObject mock pattern documented in test)
 
-- [ ] Phase 5: complete manual Cloudflare and external-service setup
+### Phase 5: complete manual Cloudflare and external-service setup
+
 - [ ] Apply Cloudflare Pages, Tiered Cache, WAF, rate limiting, and HTTPS/HSTS settings in the dashboard
 - [ ] Create or verify UptimeRobot monitors for health and HLS manifest availability
 - [ ] Capture evidence in `docs/operations/cloudflare-uptimerobot-checklist.md`
 
-- [ ] Phase 6: rehearse production deployment end to end
+### Phase 6: rehearse production deployment end to end
+
 - [ ] Provision the Hetzner host and prepare the Docker/runtime baseline
 - [ ] Configure production secrets, remote deployment, and DNS cutover
 - [ ] Run health, HLS, chat, and admin smoke tests against production-like infrastructure
 - [ ] Verify backup creation, restore, and integrity checks on the production host
 
-- [ ] Phase 7: baseline scaling and performance
+### Phase 7: baseline scaling and performance
+
 - [ ] Measure manifest TTFB and cache-hit distribution from multiple US regions
 - [x] Prepare WebSocket load-test scaffolding and summary artifacts (`ws-chat.yml`, `run-loadtests.ps1`, `summarize-artillery.ps1`)
 - [ ] Execute WebSocket throughput and chat-latency benchmarks under growing connection counts
@@ -50,44 +57,24 @@
 
 ## Status Update (2026-08-10)
 
-- Phase 1 (test fixtures) complete.
+- [x] Phase 1 (test fixtures) complete.
-- Phase 2 (viewer frontend): player startup, URL resolution, chat send/receive, reconnect, presence, DM flow, message rendering all covered (27 tests).
+- [x] Phase 2 (viewer frontend): player startup, URL resolution, chat send/receive, reconnect, presence, DM flow, message rendering all covered (27 tests).
-- Phase 3 (admin frontend): dashboard rendering, API integration, playlist management all covered (31 tests total).
+- [x] Phase 3 (admin frontend): dashboard rendering, API integration, playlist management all covered (31 tests total).
-- Phase 4 (R2 validation) partially complete: SyncToR2 cache headers + integration tests done; edge cache hit/miss remains manual.
+- [x] Phase 4 (R2 validation) partially complete: SyncToR2 cache headers + integration tests done; edge cache hit/miss remains manual.
-- Phase 5 (Cloudflare): Pages deploy workflow (`.gitea/workflows/pages-deploy.yml`) created; Pages/Workers setup docs written; manual dashboard tasks remain.
+- [ ] Phase 5 (Cloudflare): Pages deploy workflow (`.gitea/workflows/pages-deploy.yml`) created; Pages/Workers setup docs written; manual dashboard tasks remain.
-- Phase 7: Loadtest scaffolding complete; `run-loadtests.ps1` auto-generates ws-chat-summary.txt and admin-api-endpoint-summary.txt; live benchmark execution pending.
+- [ ] Phase 6 (production deployment) pending: Hetzner provisioning, secrets, DNS cutover, smoke tests, backup/restore.
+- [ ] Phase 7: Loadtest scaffolding complete; `run-loadtests.ps1` auto-generates ws-chat-summary.txt and admin-api-endpoint-summary.txt; live benchmark execution pending.
 - Version tagged 1.0.11; go vet clean.
 
-## Remaining (summary)
+## Streaming Pipeline Gaps (2026-08-10 audit → 2026-08-10 implemented)
-
-- **Test Fixtures**: media + playlist fixtures created; ffmpeg generation commands documented in test headers
-- **User Frontend Tests**: video player, chat integration, responsive, accessibility, coverage
-- **Admin Frontend Tests**: playlist UI, moderation UI, metrics dashboards, coverage
-- **Cloudflare R2 Integration Test**: upload + cache header validation done (SyncToR2 with CacheControl + ContentType); edge cache hit/miss validation remains manual
-- **Cloudflare Config**: Cloudflare Pages deploy workflow and setup docs created; manual dashboard setup (Tiered Cache, WAF, rate limiting, HTTPS/HSTS) remains pending; Pages project must be created in dashboard first.
-- **External Services**: UptimeRobot monitors + alerts
-- **Production Deployment**: Hetzner provisioning, CD pipeline, DNS cutover, smoke test
-- **Scaling & Performance**: TTFB baseline and live benchmark runs still pending; loadtest scaffolding now includes Artillery/k6 helpers with auto summaries plus worksheet field mapping; chat p95, Redis saturation, and cache-hit threshold alerting are implemented
-
-See `DEVELOPMENT.md` for detailed checklist.
-
-## Streaming Pipeline Gaps (2026-08-10 audit)
 
 STREAMING.md contract vs playlist.go/main.ts implementation. See Backlog for full details.
 
-- [ ] Continuous R2 sync during playout (HIGH) — currently only on FFmpeg exit
+- [x] Continuous R2 sync during playout (HIGH) — implemented: fsnotify watcher uploads segments within ~7s
-- [ ] Globally unique segment naming with run ID (HIGH) — currently strftime only
+- [x] Globally unique segment naming with run ID (HIGH) — implemented: `r-{ISOTIME}/seg-{seq}.m4s`
-- [ ] Atomic manifest publication with temp key (MEDIUM)
+- [x] Atomic manifest publication with temp key (MEDIUM) — implemented: upload to .tmp, then CopyObject
-- [ ] CORS headers on HLS responses from media.linearvoid.tv (MEDIUM)
+- [x] Manifest Cache-Control: add must-revalidate + s-maxage split (LOW) — implemented: `public, max-age=1, s-maxage=2, must-revalidate`
-- [ ] Player error recovery: retries, drift, reconnecting state (MEDIUM)
+- [ ] CORS headers on HLS responses from media.linearvoid.tv (MEDIUM) — infrastructure, needs Cloudflare R2 CORS config
-- [ ] Manifest Cache-Control: add must-revalidate + s-maxage split (LOW)
+- [x] Player error recovery: retries, backoff, reconnecting state (MEDIUM) — implemented: hls.on(ERROR) handler with exponential backoff
-- [ ] Health endpoint: add active item, revision, run ID, segment info (LOW)
+- [x] Health endpoint: add active item, revision, run ID, segment info (LOW) — implemented: full STREAMING.md contract fields
-
+- [x] Phase 4 edge cache validation — script `scripts/validate-edge-cache.sh` created
-## Feature List (Future Enhancements)
-
-- [ ] Admin backend
-  - [ ] Analytics: implement a settings entry to set matomo url and page id
-- [ ] User frontend
-  - [ ] Chat: add user registration and login flows
-  - [ ] Chat: private DM history and search
-  - [ ] Analytics: add javascript snippet to send pageview events to matomo

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 <!-- markdownlint-disable MD024 -->
 
+## [Unreleased]
+
+## [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.12-blue)](https://git.allucanget.biz/zwitschi/linearvoid/releases)
 [![Release Notes](https://img.shields.io/badge/release-notes-green)](CHANGELOG.md)
 
 ## Architecture
@@ -48,67 +48,173 @@ flowchart TD
 
 ## 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)
+├── docs/                   # see Documentation section below
-│   ├── src/
+├── backend/                # see Backend section below
-│   │   ├── components/        # Video player, chat sidebar, now-playing overlay
+├── frontend/               # see Frontend section below
-│   │   ├── js/                # hls.js integration, WebSocket client, UI logic
+├── infrastructure/         # see Infrastructure section below
-│   │   └── styles/            # Tailwind / custom CSS
+├── monitoring/             # see Monitoring section below
-│   ├── index.html
+├── scripts/                # see Scripts section below
-│   └── package.json           # Build tools (Vite recommended)
+├── .editorconfig           # EditorConfig for consistent coding styles
-├── backend/
+├── .env.example            # Example environment variables for local development
-│   ├── playout/               # Continuous HLS generation from playlist
+├── .gitignore              # Ignore node_modules, build artifacts, etc.
-│   │   ├── src/               # FFmpeg orchestration, playlist manager
+├── .prettierignore         # Ignore files for Prettier formatting
-│   │   ├── config/
+├── CHANGELOG.md            # Release notes and version history
-│   │   └── Dockerfile
+├── CONTRIBUTING.md         # Contribution guidelines
-│   ├── chat/                  # Real-time WebSocket service
+├── docker-compose.prod.yml # Production deployment (Hetzner + Cloudflare)
-│   │   ├── 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
+└── README.md               # This file
-└── LICENSE
 ```
 
-### 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.
+- `docs/`: Folder containing all documentation for the project, including architecture, ADRs, operational procedures, and setup guides.
-- **`backend/playout/`**: Core linear engine. FFmpeg consumes a normalized playlist and outputs continuous HLS. Includes normalization validation.
+- `docs/architecture/`: Architecture documentation, including high-level system architecture, component interactions, and decision records (ADRs).
-- **`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).
 
-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) — adds 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
 

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

@@ -16,6 +16,7 @@ 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/fsnotify/fsnotify"
 )
 
 // VideoFile represents a normalized video entry in the playlist
@@ -37,6 +38,17 @@ var (
 	restartWindow = time.Now()
 	slateDir      = "/app/slate"
 	hlsDir        = "/app/hls"
+
+	// 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
 )
 
 const (
@@ -44,11 +56,24 @@ const (
 	slateManifestName    = "playlist.m3u8"
 	// Cache-Control header values for R2 uploads.
 	segmentCacheControl  = "public, max-age=31536000, immutable"
-	manifestCacheControl = "public, max-age=2"
+	manifestCacheControl = "public, max-age=1, s-maxage=2, must-revalidate"
 )
 
-// initR2Client initializes the R2 (S3-compatible) client
+// 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 +92,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 := "live/" + 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, "live/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 + "/live/playlist.m3u8.tmp"),
+		Key:        aws.String("live/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 +439,32 @@ 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)
+	// Unhealthy if manifest has not advanced for >2 segment durations (12s)
-	fmt.Fprintf(w, `{"status":"%s","service":"playout","mode":"%s","restarts":%d,"timestamp":"%s"}`,
+	if hlsDir != "" && time.Since(lastR2PubTime) > 12*time.Second && playoutMode != "starting" {
-		status, playoutMode, restartCount, time.Now().UTC().Format(time.RFC3339))
+		status = "unhealthy"
+	}
+
+	resp := map[string]any{
+		"status":              status,
+		"service":             "playout",
+		"mode":                playoutMode,
+		"restarts":            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,
+		"timestamp":           time.Now().UTC().Format(time.RFC3339),
+	}
+	json.NewEncoder(w).Encode(resp)
 }
 
 // activateSlate copies pre-rendered slate HLS into the live output directory.
@@ -450,16 +569,19 @@ func main() {
 	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)
+		fmt.Println("R2 sync disabled:", err)
-		// Continue without R2 for local testing
 	}
 
 	// Start HTTP health check server
@@ -493,12 +615,24 @@ func main() {
 			fmt.Printf("[%s] Slate active — attempting live playout recovery...\n", time.Now().Format(time.RFC3339))
 		}
 
+		// New run ID on each restart for unique R2 segment keys (STREAMING.md)
+		initRunID()
+
 		if err := resetHLSOutput(hlsDir); err != nil {
 			fmt.Println("Failed to reset HLS output:", err)
 			time.Sleep(5 * time.Second)
 			continue
 		}
 
+		// 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)
+		}
+
 		fmt.Printf("[%s] Starting FFmpeg playout with browser-safe H.264/AAC HLS encoding...\n", time.Now().Format(time.RFC3339))
 
 		cmd := exec.Command("ffmpeg", "-re", "-f", "concat", "-safe", "0", "-i", playlistPath,
@@ -513,12 +647,14 @@ func main() {
 			"-hls_list_size", "24",
 			"-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",
+			"-hls_segment_filename", filepath.Join(hlsDir, "seg-%06d.m4s"),
-			"/app/hls/playlist.m3u8")
+			filepath.Join(hlsDir, "playlist.m3u8"))
 
 		runErr := cmd.Run()
+		if watchCancel != nil {
+			watchCancel() // Stop the filesystem watcher
+		}
 
 		// Track restart and check for slate escalation
 		restartCount++
@@ -542,24 +678,33 @@ func main() {
 			deactivateSlate()
 		}
 
-		// After FFmpeg run, sync latest segments and manifest to R2
+		// After FFmpeg run, publish remaining segments and atomic manifest to R2.
+		// Skipped when R2 is not configured.
+		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)
+			}
+		}
+
 		time.Sleep(5 * 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 := "live/" + runID + "/" + filepath.Base(f)
 		if err := SyncToR2(f, key); err != nil {
 			fmt.Printf("Failed to sync %s: %v\n", f, err)
 		} else {
@@ -567,16 +712,12 @@ func syncLatestToR2(hlsDir string) error {
 		}
 	}
 
-	// Sync the live playlist manifest (short TTL per ADR-001)
+	// Sync init segment to run-specific R2 key
-	manifestPath := filepath.Join(hlsDir, "playlist.m3u8")
-	if err := SyncToR2(manifestPath, "live/playlist.m3u8"); err != nil {
-		return err
-	}
 	initPath := filepath.Join(hlsDir, "init.mp4")
-	if err := SyncToR2(initPath, "live/init.mp4"); err != nil {
+	if err := SyncToR2(initPath, "live/"+runID+"/init.mp4"); err != nil {
 		return err
 	}
-	fmt.Println("Synced live playlist.m3u8 to R2")
+	fmt.Println("Synced init.mp4 to R2")
 
 	return nil
 }

backend/playout/src/playlist_test.go

@@ -241,11 +241,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 +261,30 @@ func TestHealthHandler(t *testing.T) {
 	}
 
 	body := w.Body.String()
-	if !strings.Contains(body, `"healthy"`) {
+	for _, want := range []string{
-		t.Errorf("body missing healthy: %s", body)
+		`"status":"healthy"`,
+		`"service":"playout"`,
+		`"mode":"live"`,
+		`"restarts":3`,
+		`"run_id":"r-20260810T120000Z"`,
+		`"last_segment_seq"`,
+		`"consecutive_failures"`,
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("body missing %q: %s", want, 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)
 	}
 }
 
 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 +299,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

docs/DEPLOYMENT.md

@@ -131,22 +131,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
+- `DATABASE_URL` — PostgreSQL connection string
-- CI_REGISTRY_NAMESPACE
+- `REDIS_URL` — Redis connection string
-- CHAT_PORT
+- `ADMIN_USERNAME` / `ADMIN_PASSWORD` — admin dashboard credentials
-- NGINX_PORT
+- `ADMIN_SESSION_TTL_HOURS` — session expiry (default 12)
-- DATABASE_URL (if overridden)
+- `VITE_PUBLIC_APP_URL` / `VITE_PUBLIC_WS_URL` / `VITE_PUBLIC_HLS_URL` — frontend URLs
-- 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
 
-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/Pages):**
+
+- `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
 

docs/DEVELOPMENT.md

@@ -1,116 +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 deploy workflow created (`.gitea/workflows/pages-deploy.yml`); setup docs written (`docs/operations/cloudflare-pages-setup.md`, `docs/operations/gitea-cloudflare.pages.md`).
-
-- [ ] Cloudflare Pages: create project in dashboard, link custom domain, or deploy via Gitea Actions Direct Upload
-- [ ] 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)
-- [x] Load-test scaffolding: ws-chat.yml, admin-api.js, run-loadtests.ps1, summarizers, README
-- [x] Cache-hit ratio exporter (scripts/cache-hit-ratio.js + .ps1)
-- [x] Saturation alerts: chat p95 latency, Redis memory usage, cache-hit ratio
-- [ ] Track cache hit ratio: Cloudflare GraphQL → Grafana panel, alert <90%
-- [ ] Capacity triggers: Prometheus rules for cache-miss >10%/15min, CPU >80%/10min (chat p95, Redis memory, cache-hit already done)
-- [ ] 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
-
-## Streaming Pipeline (2026-08-10 audit)
-
-Gaps between STREAMING.md contract and playlist.go/main.ts implementation:
-
-- [ ] **Continuous R2 sync during playout (HIGH)**: `syncLatestToR2()` runs only after FFmpeg exits. Needs per-segment upload via filesystem watch or FFmpeg progress pipe.
-- [ ] **Globally unique segment naming (HIGH)**: Add run/session UUID + monotonic sequence. Currently `strftime` only — collisions possible.
-- [ ] **Atomic manifest publication (MEDIUM)**: Upload to temp key then atomically replace `live/playlist.m3u8`.
-- [ ] **Manifest Cache-Control alignment (LOW)**: Add `must-revalidate` and `s-maxage`/`max-age` split.
-- [ ] **CORS headers on HLS responses (MEDIUM)**: Add `Access-Control-Allow-Origin` to Worker or R2 custom domain.
-- [ ] **Player error recovery (MEDIUM)**: Add `hls.on(Hls.Events.ERROR, ...)` with retries, drift, reconnecting state.
-- [ ] **Health endpoint detail (LOW)**: Add active item, playlist revision, run ID, segment info, R2 pub timestamp.
-- [x] Source media contract + validation — implemented
-- [x] fMP4 HLS packaging (6s, 24 window) — implemented
-- [x] Slate fallback + recovery — implemented
-- [x] R2 cache headers (immutable segments, short-lived manifest) — implemented
-- [x] Cloudflare Worker immutable `.m4s` headers — implemented

docs/README.md

@@ -6,6 +6,15 @@ 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 and Pages.
+  - [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.
+  - [Prometheus CURL Windows](./infrastructure/monitoring/prometheus_curl_win.md) - Prometheus metrics endpoint testing with curl on Windows.
+
 ## API
 
 - [API](API.md) - Implemented WebSocket and REST API reference.
@@ -30,12 +39,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

@@ -5,7 +5,7 @@ This guide covers prerequisites, environment setup, running the application loca
 ## 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`).
 - **FFmpeg**: Used by the playout service for HLS generation. Install via `apt install ffmpeg` (Linux), Homebrew (macOS), or Winget (Windows).

docs/architecture/README.md

@@ -87,12 +87,7 @@
 
 ## Companion Documentation
 
-- [API.md](../API.md) - Implemented WebSocket and REST API reference.
+see [Documentation README](../README.md) for an overview of all documentation, including architecture, ADRs, operational procedures, and setup guides.
-- [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.
 
 ## Introduction and Goals
 
@@ -727,7 +722,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 Pages 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.
 

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.                                                                          |

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 `https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pages/projects` to verify the account ID and API token are valid.
+
+## 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 curl
+$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 Pages projects for the account
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$env:CLOUDFLARE_ACCOUNT_ID/pages/projects" -H "Authorization: Bearer $env:CLOUDFLARE_API_TOKEN" -H "Content-Type: application/json"
+
+# Create a new Pages project (if needed)
+# curl -X POST "https://api.cloudflare.com/client/v4/accounts/$env:CLOUDFLARE_ACCOUNT_ID/pages/projects" -H "Authorization: Bearer $env:CLOUDFLARE_API_TOKEN" -H "Content-Type: application/json" -d '{"name":"linearvoid","production_branch":"main"}'
+```

docs/operations/cloudflare-pages-setup.md

@@ -12,13 +12,13 @@ Both are managed under **Workers & Pages** in the Cloudflare dashboard.
 ## Dashboard URLs
 
 | Resource                 | URL                                                                                                                 |
-| ------------------------ | ---------------------------------------------------------------------------------------------- |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| Workers & Pages overview | `https://dash.cloudflare.com/{accountId}/workers-and-pages`                                    |
+| Workers & Pages overview | `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers-and-pages`                                    |
-| Worker: linearvoid       | `https://dash.cloudflare.com/{accountId}/workers/services/view/linearvoid/production/settings` |
+| Worker: linearvoid       | `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers/services/view/linearvoid/production/settings` |
-| Pages project            | `https://dash.cloudflare.com/{accountId}/pages/view/linearvoid`                                |
+| Pages project            | `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/pages/view/linearvoid`                                |
 | API tokens               | <https://dash.cloudflare.com/profile/api-tokens>                                                                    |
 
-## 1) Worker: `linearvoid` (edge cache headers)
+## 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.
 
@@ -30,31 +30,34 @@ npx wrangler deploy infrastructure/cloudflare/worker.js
 
 Or paste into the Workers dashboard at the URL above (Quick Edit).
 
-## 2) Pages: Static frontend
+## Pages: Static frontend
 
-Two approaches — pick one:
+### Direct Upload via Gitea Actions
-
-### Option A: Git integration (recommended)
-
-Connect the Gitea repository directly in Cloudflare Pages:
-
-1. Pages → Create a project → Connect to Git
-2. Link `git.allucanget.biz/zwitschi/linearvoid`
-3. Build command: `cd frontend && npm run build`
-4. Output directory: `frontend/dist`
-5. Add custom domain: `linearvoid.tv`
-
-Cloudflare handles builds and deploys automatically on push.
-
-> **Naming:** If `linearvoid` is already used by the Worker service, name the Pages project `linearvoid-site` (or similar). Workers and Pages share a namespace.
-
-### Option B: Direct Upload via Gitea Actions
 
 Use `.gitea/workflows/pages-deploy.yml` to build in Gitea Actions and upload via the Cloudflare API.
 
 See [gitea-cloudflare-pages.md](./gitea-cloudflare-pages.md) for the workflow.
 
-## 3) Custom domains
+### Variables and secrets
+
+On Cloudflare pages, set the following environment variables (needed to run the frontend)
+
+| Type      | Name                                   | Value                                           |
+| --------- | -------------------------------------- | ----------------------------------------------- |
+| Secret    | ADMIN_PASSWORD                         | `not-a-real-admin-password`                     |
+| Plaintext | ADMIN_SESSION_TTL_HOURS                | `12`                                            |
+| Plaintext | ADMIN_USERNAME                         | `boogers`                                       |
+| Plaintext | HLS_SEGMENT_DURATION                   | `6`                                             |
+| Plaintext | HLS_WINDOW_SIZE                        | `24`                                            |
+| Plaintext | PLAYLIST_PATH                          | `/app/playlist/playlist.txt`                    |
+| Plaintext | VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR    | `boogers`                                       |
+| Plaintext | VITE_PUBLIC_ADMIN_DEFAULT_ROOM         | `main`                                          |
+| Plaintext | VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT | `50`                                            |
+| Plaintext | VITE_PUBLIC_APP_URL                    | `https://linearvoid.tv`                         |
+| Plaintext | VITE_PUBLIC_HLS_URL                    | `https://media.linearvoid.tv/hls/playlist.m3u8` |
+| Plaintext | VITE_PUBLIC_WS_URL                     | `wss://linearvoid.tv/ws`                        |
+
+## Custom domains
 
 - `linearvoid.tv` → Pages project
 - `www.linearvoid.tv` → redirect to `linearvoid.tv`

docs/operations/gitea-cloudflare-pages.md

@@ -6,7 +6,12 @@ Deploy the Linear Void frontend (Vite + TypeScript SPA) from Gitea to Cloudflare
 
 ## Prerequisites
 
-1. **Cloudflare Pages project** created (Dashboard → Workers & Pages → Create → Pages), see [Cloudflare Pages Setup](./cloudflare-pages-setup.md).
+> **Important:** The Pages project must exist before the API deploy call works. You'll get error 8000007 ("Project not found") if you skip this step.
+
+1. **Cloudflare Pages project** created first:
+   - Dashboard → Workers & Pages → Create → Pages → Direct Upload
+   - Name it `linearvoid` (or a different name if `linearvoid` is already taken by a Worker — see note below)
+   - See [Cloudflare Pages Setup](./cloudflare-pages-setup.md) for full details.
 2. **Project name**: note the exact name (e.g., `linearvoid`).
 3. **API token** with Pages permissions:
    - Create at <https://dash.cloudflare.com/profile/api-tokens>
@@ -14,6 +19,8 @@ Deploy the Linear Void frontend (Vite + TypeScript SPA) from Gitea to Cloudflare
    - Store in Gitea → Settings → Secrets as `CLOUDFLARE_API_TOKEN`
 4. **Account ID** from Cloudflare dashboard overview → store as `CLOUDFLARE_ACCOUNT_ID`
 
+> **Naming conflict:** If a Worker already exists with the name `linearvoid`, the Pages project must use a different name (e.g., `linearvoid-site`). Update the `projectName` in the workflow accordingly. Workers and Pages share a namespace under "Workers & Pages".
+
 ## Project-specific values
 
 | Setting            | Value                                                      |
@@ -46,7 +53,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Install dependencies
         run: cd frontend && npm ci
@@ -64,24 +71,50 @@ jobs:
           gitHubToken: ${{ secrets.GITEA_TOKEN }}
 ```
 
-If the `cloudflare/pages-action@v1` action is unavailable from Gitea, use the direct API approach:
+If the `cloudflare/pages-action@v1` action is unavailable from Gitea, use the direct Cloudflare Pages API (multipart/form-data with manifest):
+
+Snippet to generate a manifest in format `-F manifest='{"index.html": "abc123", "style.css": "def456"}'`
+
+```bash
+# Build manifest form argument from all files in frontend/dist
+form_args="-F manifest={"
+for file in $(find frontend/dist -type f | sed 's|^frontend/dist/||'); do
+  hash=$(sha256sum "frontend/dist/$file" | awk '{print $1}')
+  form_args="$form_args\"$file\":\"$hash\","
+done
+form_args="${form_args%,}}" # remove trailing comma and close JSON
+```
 
 ```yaml
-- name: Create deployment artifact
+- name: Generate deployment manifest
-  run: tar -czf site.tgz -C frontend/dist .
+  run: |
+    cd frontend/dist
+    form_args="-F manifest={"
+    for file in $(find . -type f ! -name manifest.json | sed 's|^\./||'); do
+      hash=$(sha256sum "$file" | awk '{print $1}')
+      form_args="$form_args\"$file\":\"$hash\","
+    done
+    form_args="${form_args%,}}" # remove trailing comma and close JSON
+    echo "Form arguments: $form_args"
+    echo "FORM_ARGS=$form_args" >> $GITHUB_ENV
 
 - name: Deploy to Cloudflare Pages
   env:
     CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
     CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
   run: |
+    cd frontend/dist
+    form_args="$FORM_ARGS" # use form arguments generated in previous step
+    COMMIT_HASH=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
     curl -sS -X POST \
       "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pages/projects/linearvoid/deployments" \
       -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
-      -H "Content-Type: application/octet-stream" \
+      -F "commit_hash=${COMMIT_HASH}" \
-      --data-binary @site.tgz
+      $form_args
 ```
 
+This matches the Cloudflare Pages Direct Upload API: `Content-Type: multipart/form-data`, each file as a separate form field, and a `manifest` JSON mapping filenames to SHA-256 hashes.
+
 ## Secrets to add in Gitea
 
 | Secret                  | Value                                |
@@ -102,8 +135,10 @@ If the `cloudflare/pages-action@v1` action is unavailable from Gitea, use the di
 - Multi-page SPA (`vite.config.ts`) produces three entry points — Cloudflare Pages serves them correctly.
 - For SPA fallback routing, add a `frontend/public/_redirects` file with `/* /index.html 200` before building.
 - If deployments fail with 403, verify the API token has `Account → Cloudflare Pages → Edit` permission.
+- If you get error **8000007** ("Project not found"), the Pages project hasn't been created yet. Create it via the Cloudflare dashboard (Workers & Pages → Create → Pages → Direct Upload) first, then re-run.
+- If `linearvoid` is already taken by a Worker, use a different project name like `linearvoid-site` and update the `projectName` and `PROJECT_NAME` values in the workflow.
 
 ## Related resources
 
-- Cloudflare Workers dashboard: `https://dash.cloudflare.com/{accountId}/workers/services/view/linearvoid/production/settings` — for managing the `infrastructure/cloudflare/worker.js` deployment
+- Cloudflare Workers dashboard: `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers/services/view/linearvoid/production/settings` — for managing the `infrastructure/cloudflare/worker.js` deployment
-- Cloudflare Pages project: `https://dash.cloudflare.com/{accountId}/pages/view/linearvoid` — deployment history and custom domain settings
+- Cloudflare Pages project: `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/pages/view/linearvoid` — deployment history and custom domain settings

docs/operations/gitea-cloudflare.pages.md

@@ -1,118 +0,0 @@
-# Gitea to Cloudflare Pages — Linear Void
-
-## Goal
-
-Deploy the Linear Void frontend (Vite + TypeScript SPA) from Gitea to Cloudflare Pages using Gitea Actions.
-
-## Prerequisites
-
-> **Important:** The Pages project must exist before the API deploy call works. You'll get error 8000007 ("Project not found") if you skip this step.
-
-1. **Cloudflare Pages project** created first:
-   - Dashboard → Workers & Pages → Create → Pages → Direct Upload
-   - Name it `linearvoid` (or a different name if `linearvoid` is already taken by a Worker — see note below)
-   - See [Cloudflare Pages Setup](./cloudflare-pages-setup.md) for full details.
-2. **Project name**: note the exact name (e.g., `linearvoid`).
-3. **API token** with Pages permissions:
-   - Create at <https://dash.cloudflare.com/profile/api-tokens>
-   - Permission: `Account → Cloudflare Pages → Edit`
-   - Store in Gitea → Settings → Secrets as `CLOUDFLARE_API_TOKEN`
-4. **Account ID** from Cloudflare dashboard overview → store as `CLOUDFLARE_ACCOUNT_ID`
-
-> **Naming conflict:** If a Worker already exists with the name `linearvoid`, the Pages project must use a different name (e.g., `linearvoid-site`). Update the `projectName` in the workflow accordingly. Workers and Pages share a namespace under "Workers & Pages".
-
-## Project-specific values
-
-| Setting            | Value                                                      |
-| ------------------ | ---------------------------------------------------------- |
-| Framework          | Vite + TypeScript                                          |
-| Build command      | `cd frontend && npm install && npm run build`              |
-| Output directory   | `frontend/dist`                                            |
-| Node version       | 20                                                         |
-| Multi-page entries | `index.html`, `admin/index.html`, `admin/login/index.html` |
-
-## Gitea Actions workflow
-
-Create `.gitea/workflows/pages-deploy.yml`:
-
-```yaml
-name: Deploy to Cloudflare Pages
-
-on:
-  push:
-    branches: ["main"]
-  workflow_dispatch: {}
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install dependencies
-        run: cd frontend && npm ci
-
-      - name: Build
-        run: cd frontend && npm run build
-
-      - name: Deploy to Cloudflare Pages
-        uses: cloudflare/pages-action@v1
-        with:
-          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          projectName: linearvoid
-          directory: frontend/dist
-          gitHubToken: ${{ secrets.GITEA_TOKEN }}
-```
-
-If the `cloudflare/pages-action@v1` action is unavailable from Gitea, use the direct API approach:
-
-```yaml
-- name: Create deployment artifact
-  run: tar -czf site.tgz -C frontend/dist .
-
-- name: Deploy to Cloudflare Pages
-  env:
-    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-  run: |
-    curl -sS -X POST \
-      "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pages/projects/linearvoid/deployments" \
-      -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
-      -H "Content-Type: application/octet-stream" \
-      --data-binary @site.tgz
-```
-
-## Secrets to add in Gitea
-
-| Secret                  | Value                                |
-| ----------------------- | ------------------------------------ |
-| `CLOUDFLARE_API_TOKEN`  | API token with Pages:Edit permission |
-| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare account ID from dashboard |
-
-## 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 Pages** → Deployments for the new deployment.
-4. Visit the `.pages.dev` preview URL, then promote to `linearvoid.tv` when ready.
-
-## Notes
-
-- The existing `ci.yml` already builds the frontend; the Pages deploy workflow is additive and independent.
-- Multi-page SPA (`vite.config.ts`) produces three entry points — Cloudflare Pages serves them correctly.
-- For SPA fallback routing, add a `frontend/public/_redirects` file with `/* /index.html 200` before building.
-- If deployments fail with 403, verify the API token has `Account → Cloudflare Pages → Edit` permission.
-- If you get error **8000007** ("Project not found"), the Pages project hasn't been created yet. Create it via the Cloudflare dashboard (Workers & Pages → Create → Pages → Direct Upload) first, then re-run.
-- If `linearvoid` is already taken by a Worker, use a different project name like `linearvoid-site` and update the `projectName` and `PROJECT_NAME` values in the workflow.
-
-## Related resources
-
-- Cloudflare Workers dashboard: `https://dash.cloudflare.com/{accountId}/workers/services/view/linearvoid/production/settings` — for managing the `infrastructure/cloudflare/worker.js` deployment
-- Cloudflare Pages project: `https://dash.cloudflare.com/{accountId}/pages/view/linearvoid` — deployment history and custom domain settings

frontend/index.html

@@ -71,6 +71,11 @@
       </section>
     </main>
 
+    <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 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",
+      "version": "3.3.18",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.16.tgz",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
-      "integrity": "sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==",
+      "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.12",
   "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/src/admin.test.ts

@@ -271,3 +271,58 @@ 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");
+  });
+});

frontend/src/main.test.ts

@@ -13,7 +13,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 +73,47 @@ 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>
+          <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>
   `;
 
   // Stub prompt for DM
@@ -331,8 +353,98 @@ 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("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");
+  });
+});

frontend/src/main.ts

@@ -18,6 +18,11 @@ let username = "viewer" + Math.floor(Math.random() * 1000);
 let chatVisible = true;
 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;
@@ -25,6 +30,7 @@ export function resetViewerStateForTests() {
   username = "viewer";
   chatVisible = true;
   onlineUsers.clear();
+  playerErrorCount = 0;
 }
 
 export function resolveWebSocketBaseUrl() {
@@ -159,10 +165,60 @@ 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 +235,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");

frontend/src/style.css

@@ -1056,3 +1056,40 @@ 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,
+      },
+    },
   },
 });

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