Initial commit: watch-together phases 0-4 + presence hardening, internet-tested

docs/ARCHITECTURE.md

@@ -0,0 +1,77 @@
+# ARCHITECTURE
+
+One binary, three modes. `packages/server` (Relic) is embedded, not a separate product.
+
+- **Client**: GUI Join, sync WS client (`web_socket_channel` in `packages/core`) + mpv. No server code runs.
+- **Server+Client (Host)**: GUI Host starts `packages/server` in-process, binds port, self-connects via loopback. Host opens ports, runs traffic. Clients open nothing outbound-only.
+- **Headless**: `--headless`, same server package, no window/player init.
+
+Server side: **Relic** (HTTP + built-in WS). Client side WS: **`web_socket_channel`**
+(Relic has no client; server WS handling stays in Relic).
+
+Media order (locked): links first (shared http(s) URL, Syncplay-style sync),
+file relay after (server-proxied bytes for the whitelist case).
+
+## Media paths (links vs file relay)
+
+Two ways to watch, same sync engine, same Range endpoint:
+
+1. **Links (primary, shipped):** host shares an http(s) media URL
+   (e.g. a Jellyfin Download URL). Viewers stream it directly; the
+   server is sync-authority only (`media.url`, no `mediaUrl`). This
+   covers most sessions — proxying is usually unnecessary.
+2. **File relay (secondary, local-file half shipped):** host serves
+   bytes from their own machine through the server's token-gated
+   Range endpoint `GET /m/<sid>/<token>/<name>`. Viewers (and the
+   host via loopback) play the server URL. This is the fallback for
+   the whitelist case: viewers cannot reach the source, but the
+   server/host can (e.g. Jellyfin allowlists the host, not the
+   viewers). No server storage — bytes stream file→socket, config +
+   logs only, never to disk.
+
+Backends behind `MediaSource` (`packages/core/lib/src/media_source.dart`):
+`FileMediaSource` (local file — SHIPPED, wired into
+`mountSessionMediaRoute`); `HttpSource` (server fetches a remote URL
+and re-serves it — DEFERRED, Phase 8). `resolveMediaRequest` stays
+framework-agnostic so both ride the same tested Range table.
+
+## Deferred: remote-host upload tunnel (NOT active protocol)
+
+If a VPS tier ever needs a *remote* host to push bytes to a server
+it cannot serve from disk, the reserved design is the brief's WSS
+tunnel: host dials out, JSON control frames
+(`hello`/`welcome`+mediaUrl, `open`{id,start,end}, `ack`, `cancel`,
+`eof`/`err`) plus binary `[u32 BE reqId][payload]` chunks —
+chunk 256 KiB, credit window 8 (≈2 MiB in flight), max 16 concurrent
+`open`, relay acks only after socket flush (real backpressure).
+`RelayConstants.chunkBytes/creditWindowChunks/maxConcurrentOpen`
+are reserved for this. No code exists; direct-serve covers v1
+(host IS the server, opens ports itself).
+
+Host playback goes through loopback like everyone else's
+(`http://127.0.0.1:<port>/…`) — same code path as remote viewers, so
+server bugs surface on the host screen first. Deployment ladder,
+cheapest first: host's own PC (LAN, or internet with port-forward) →
+same binary `--headless` on a friend's always-on box → cheap VPS
+(CGNAT escape; TLS/Caddy deferred with this tier).
+
+Sync: heavily Syncplay-inspired + original readiness design, NOT 1:1
+(audit done; deviations: clock never moves from reports, no
+pause-on-leave, force-for-all, quorum gate — see HANDOFF §2).
+Additive namespaced extensions only, `proto` bump + `PROTOCOL.md` same-commit.
+
+No server storage: config + logs only. Media never touches disk.
+
+## Health reporting (standing rule)
+
+Every failure must display. Nothing stalls silently.
+
+- Server `/health` returns machine-readable status: ok, room, viewer
+  count, uptime, media, bytes served, version. The app reads it.
+- App surfaces all failure states in UI with cause + what-to-do:
+  connecting/reconnecting, wrong secret (401), kicked (403), session
+  gone (410), host offline / buffering (503), starvation
+  ("waiting for X — N.N s buffered"). Backed by a structured status
+  signal (severity + message), not bare strings.
+- Errors log via `debugPrint` + stack trace at the boundary, then
+  convert to a displayable state. No swallowed exceptions.