From c365247ca0de3255ac0e0cf8294873d516081ea1 Mon Sep 17 00:00:00 2001
From: Blade <blade@darkness.services>
Date: Tue, 10 Mar 2026 23:22:09 -0400
Subject: [PATCH] Add deployment README for darkness.services setup

---
 README.darkness.md | 149 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 README.darkness.md

diff --git a/README.darkness.md b/README.darkness.md
new file mode 100644
index 0000000..af7b217
--- /dev/null
+++ b/README.darkness.md
@@ -0,0 +1,149 @@
+# SafeTwitch Deployment Notes (darkness.services)
+
+This document describes the practical changes made in this repo to stabilize and run SafeTwitch reliably on `safetwitch.darkness.services` and `api.safetwitch.darkness.services`.
+
+## Goals
+
+- Keep the stack self-hostable with Docker Compose.
+- Improve live playback reliability (especially around ads and quality switches).
+- Restore useful search behavior even when backend search responses are empty.
+- Keep clearnet and onion routes available.
+
+## Infrastructure and Build Changes
+
+### 1. Frontend image is built locally
+
+Files:
+- `docker/Dockerfile`
+- `docker/docker-compose.yml`
+
+Changes:
+- Node build stage moved to `node:22`.
+- Frontend build command changed to `npm run build-only` for consistent container builds.
+- Frontend services in compose now use local image build (`safetwitch-local:latest`).
+
+Why:
+- Ensures source-level fixes are actually deployed, instead of being masked by a prebuilt image.
+
+### 2. Frontend reverse proxy behavior fixed
+
+File:
+- `docker/nginx.conf`
+
+Changes:
+- Added explicit forwarding for:
+  - `/api/` -> backend API
+  - `/proxy/` -> backend proxy
+
+Why:
+- Some playlists and media URLs are emitted as frontend-host paths (`/proxy/...`).
+- Without these proxy routes, users see missing images/icons and stalled stream playback.
+
+### 3. Compose routing and service layout
+
+File:
+- `docker/docker-compose.yml`
+
+Changes:
+- Clearnet and tor frontend/backend services retained.
+- Traefik labels and host routing aligned for:
+  - `safetwitch.darkness.services`
+  - `api.safetwitch.darkness.services`
+  - onion equivalents
+
+## Playback and UX Reliability Changes
+
+### 4. Player recovery logic for stuck live streams
+
+File:
+- `src/components/VideoPlayer.vue`
+
+Changes:
+- Added auto-recovery handlers for media stall scenarios:
+  - `waiting`, `stalled`, `error`, and live `ended` transitions.
+- Added watchdog loop for live streams:
+  - if time does not advance for several seconds, attempt recovery.
+- Recovery strategy:
+  - soft resume with `play()`
+  - hard resume by reloading source, then seeking appropriately and resuming.
+
+Why:
+- Prevents cases where ad transitions or stream discontinuities leave the player hanging until manual restart.
+
+### 5. Quality selector stability and defaults
+
+Files:
+- `src/assets/qualitySelector.ts`
+- `src/settingsManager.ts`
+- `src/locales/en.json`
+
+Changes:
+- Added explicit `Auto` quality option.
+- Default quality changed to `Auto` for new settings.
+- Quality selection now behaves as an adaptive cap (selected quality and below), not a brittle single-rendition lock.
+- Added safer startup fallback when chosen quality is unavailable.
+- Ensure playback resumes after quality changes.
+
+Why:
+- Reduces buffering and prevents quality-switch dead-ends.
+
+### 6. Live status fallback for stale backend `api/users`
+
+Files:
+- `src/views/UserView.vue`
+- `src/components/StreamPreview.vue`
+
+Changes:
+- If `api/users` reports offline or missing stream, fallback to `api/users/isLive/bulk`.
+- For confirmed live users without stream metadata, synthesize minimal stream data to avoid UI breakage.
+
+Why:
+- Handles backend variants where user detail endpoints can be stale while bulk live status is still accurate.
+
+## Search Fixes
+
+### 7. Frontend search page hardening
+
+File:
+- `src/views/SearchPageView.vue`
+
+Changes:
+- Search now re-runs when query changes (route watcher).
+- Added fallback behavior when backend search returns empty:
+  - user lookup
+  - category matching from discover data
+
+Why:
+- Avoids blank pages from route update edge cases or empty backend responses.
+
+### 8. Backend-level search fallback service
+
+Files:
+- `docker/search-fallback/server.mjs`
+- `docker/docker-compose.yml`
+
+Changes:
+- Added `safetwitch-search-fallback` service.
+- Traefik routes `/api/search` requests to this service (clearnet + tor API hosts).
+- Fallback service behavior:
+  - use backend search first
+  - if empty, perform targeted fallback lookups
+  - includes numeral normalization (`4` <-> `IV`) for queries like `diablo 4` and `Diablo IV`.
+
+Why:
+- Provides a backend-level mitigation without replacing the rest of the API stack.
+
+## Operational Notes
+
+- If the UI appears stale after deployment, do a hard refresh (`Ctrl+Shift+R`).
+- For HLS diagnostics, use real `GET` checks. `HEAD` may be misleading for some playlist endpoints.
+- Existing users may keep old local settings until changed in Settings.
+
+## Validation Checklist
+
+- `https://safetwitch.darkness.services` loads.
+- `https://safetwitch.darkness.services/api/discover` returns JSON.
+- Live playback resumes after quality change.
+- Live playback recovers after ad transition/stall.
+- `https://api.safetwitch.darkness.services/api/search/?query=diablo+4` returns category data.
+- Onion routes remain available for frontend/backend tor services.