Watch party refresh: Chat/Queue/Room tabs, host transport, gentle sync, heartbeat and latency-aware reconnect, in-place section updates

docs/watch-party-refresh.md

@@ -0,0 +1,37 @@
+# Watch party refresh
+
+Branch: `feat/watch-party-refresh`, based on local `main` at `2309791`.
+Worktree: `/home/josh/development/personal/ytplayer-watch-party`.
+
+## Implemented
+
+- Compact Chat / Queue / Room interface, with the host's Play/Pause, ±10 seconds and Next controls always above the tabs.
+- Invitation code and Copy link stay visible. Guest playback remains subject to the existing host permission rules.
+- Room includes audio-only playback (uses the existing player setting), a persistent Gentle sync preference, round-trip connection timing, voice, presentation and lyrics controls.
+- Gentle sync permits four seconds of drift during playback and limits correction seeks to once every eight seconds; strict mode retains the 1.5-second tolerance. Neither mode corrects playing media while it is already seeking or buffering. Paused state still mirrors the host.
+- Bounded exponential reconnect with jitter, online recovery, socket identity checks, periodic heartbeat and latency-aware clock offset. Guests wait when the host is absent instead of following a stale timeline.
+- DOM sections update only when their data changes. Chat appends new messages, preserves history scroll position, and offers Jump to latest. Drafts remain intact through membership/reconnect updates and failed offline sends.
+- Queue updates preserve the search input and search results. The DJ feature loads when its tab is opened.
+- Small-screen controls remain above navigation; short viewports use a more compact arrangement. No new runtime dependencies.
+
+## Validation
+
+From this worktree, with npm development dependencies installed and Chromium available:
+
+```sh
+node --test tests/watch-party-browser.cjs
+node --test frontend/party-dj.test.js frontend/app-seams.test.js
+cd server
+bun test ./party.test.js ./party-dj.test.js
+```
+
+The browser suite starts an isolated loopback Bun relay, opens host and guest browser contexts, and checks controls, draft preservation, buffering/correction cooldown, queue search persistence, chat scroll, offline reconnect, timing and narrow-screen layout. Its playback engine is a deterministic fixture: these checks do not measure actual video throughput, codecs, battery use or live voice quality. Existing server tests cover host authority, seat ownership, chat, DJ, presentations and room lifecycle.
+
+Audio-only savings depend on whether a separate audio rendition is available; this change does not create lower-bitrate server renditions. Gentle sync deliberately allows more playback drift in exchange for fewer disruptive seeks. Voice still uses the existing STUN-only mesh.
+
+## Further improvements worth a separate change
+
+1. Participant readiness/buffering indicators, with an opt-in host “wait for everyone” policy. Needs a bounded readiness protocol and a timeout so one offline guest cannot stall the room.
+2. Low-bitrate video renditions for server-cached uploads. Requires storage/transcoding budgets and device-compatible codec choices; lowering the quality selector alone cannot reduce a single cached file's bitrate.
+3. Acknowledged chat delivery and retry IDs. Avoid silent server flood-limit drops and duplicates after reconnect.
+4. TURN relay and voice connection diagnostics for networks where the existing peer-to-peer voice mesh cannot connect.