feat: Add protocol spec, rate limiting, vitest framework, and documentation

## Added
- **WebSocket Protocol Specification** (docs/PROTOCOL.md) - Complete reference
  for all 20+ events with payload schemas, rate limits, and edge cases
- **LEAVE_ROOM Rate Limiting** - 10 requests/socket/minute to prevent abuse
- **Vitest Testing Framework** - Modern test setup with coverage reporting
- **Host Control Mode Documentation** - Consolidated EN documentation
  (docs/host-control-mode.md) with references to internal implementation

## Changed
- **Graceful Shutdown** - Socket.IO clients properly disconnected during
  server shutdown (server/index.js)
- **CI Workflow** - Added test step with continue-on-error for gradual rollout
- **README** - Added protocol documentation link
- **CHANGELOG** - Updated with all new features and improvements

## Moved
- Internal documentation moved to docs/internal/ for better organization
- Host Control Mode docs consolidated from 4 files to 1 comprehensive guide

## Technical Details
- Protocol spec: 495 lines, covers all events from shared/constants.js
- Rate limiter: Follows existing pattern (checkAuthRate, checkEventRate)
- Vitest: 6 tests for rate limiter, all passing
- Documentation: Host Control Mode doc includes edge cases, testing checklist,
  architecture decisions

docs/internal/host-control-mode-COHOST-PLAN.md

@@ -0,0 +1,118 @@
+# Co-Host (Multi-Controller) — Implementation Plan
+
+Branch base: `feature/host-control-mode` (builds directly on it).
+Goal: let the room owner grant **playback control to several peers** (co-hosts), not
+just one — e.g. 4 of N people in a room may drive play/pause/seek, the rest are guests.
+
+This is the second server-gated feature the `capabilities` hook was designed for
+(`CAPABILITIES.CO_HOST = 'co-host'`, already stubbed in `shared/constants.js`).
+
+---
+
+## 1. Roles
+
+| Role | Can drive (play/pause/seek/force-sync/episode-lobby) | Can promote/demote + toggle mode |
+|------|------|------|
+| **Owner** (room creator, = today's "host") | yes (always a controller) | **yes** |
+| **Controller** (co-host) | yes (in `host-only` mode) | no |
+| **Guest** | only in `everyone` mode | no |
+
+The single-host feature is just the special case `controllers = { owner }`.
+
+## 2. Data model
+
+### Server (`room` object)
+- `ownerPeerId` — the creator / manager. Keep `hostPeerId` as an **alias** (= ownerPeerId)
+  so older clients keep working.
+- `controllers: Set<peerId>` — peers allowed to drive. **Always contains ownerPeerId.**
+- `controlMode: 'everyone' | 'host-only'` — unchanged wire values (`'host-only'` now means
+  "restricted to controllers", not "single host").
+- `MAX_CONTROLLERS` cap (e.g. 10) to bound the set + payload.
+
+### Shared constants
+- `CAPABILITIES.CO_HOST = 'co-host'` (un-stub it) → add to `SERVER_CAPABILITIES`.
+- New events:
+  - `SET_PEER_ROLE` (client→server): `{ peerId, controller: boolean }` — owner promotes/demotes.
+  - Extend `CONTROL_MODE` (server→client) payload: `{ controlMode, ownerPeerId, hostPeerId, controllers: [peerId...] }`.
+- `ROOM_DATA` gains `ownerPeerId` + `controllers`.
+
+## 3. Gate generalization (the core change)
+
+Today the gate compares against a single `hostPeerId`. Generalize to set membership:
+
+- **Server relay gate** (`server/index.js`): `controlMode === 'host-only' && !room.controllers.has(mapping.peerId)` → drop. (Was `mapping.peerId !== room.hostPeerId`.)
+- **Background gates** (sender + receiver): replace `amHost()` / `senderId !== hostPeerId`
+  with controller-set membership: `controllers.includes(myPeerId)` / `senderId ∈ controllers`.
+- **Helpers:** split `amHost()` into `amOwner()` (manage rights) and `amController()`
+  (drive rights). The desync/snap-back path keys on `!amController()` instead of `!amHost()`.
+
+`SET_PEER_ROLE` handler (server): validate sender is owner, target is a current peer in the
+room, enforce `MAX_CONTROLLERS`, always keep owner in the set, then broadcast `CONTROL_MODE`
+with the new `controllers`.
+
+## 4. Client + UI
+
+- **Owner** sees the peer list with a per-peer **"Controller" toggle** (promote/demote) plus
+  the existing mode toggle.
+- **Controllers** see a "Controller" badge and are NOT locked out of the remote-control buttons.
+- **Guests** see "Guest" + the host-only notice (unchanged).
+- The promote UI + co-host badges render only when the relay advertises the `co-host`
+  capability (feature detection, same pattern as `hostControlSupported`).
+- i18n: new keys (`ROLE_CONTROLLER`, `BTN_PROMOTE`, `BTN_DEMOTE`, …) across all locales.
+
+## 5. Backwards compatibility
+
+- **New client + old server** (host-control only, no `co-host` capability): no co-host UI;
+  behaves as today's single-host. ✓
+- **Old client + new server**: ignores `controllers` / `SET_PEER_ROLE`. An old client that
+  the owner promotes still **gates itself** (its sender-gate only knows `!amHost`), so it
+  can't drive — it degrades to a guest. Co-host requires a client that understands
+  `controllers`. Document this; not a crash. ✓
+- No `PROTOCOL_VERSION` bump needed — purely additive, same as host-control.
+
+## 6. Edge cases
+- **Controller leaves** → `removePeerFromRoom` also does `room.controllers.delete(peerId)`.
+- **Owner leaves** → fallback: promote the earliest remaining **controller** to owner (prefer
+  a controller over a random peer); if none, earliest peer; keep the rest of the set. Reuse
+  the `peerJoinLocks` guard so a reconnect/second-tab doesn't demote (same fix as host).
+- **Promote a peer not in the room** → server rejects (target must be a live peer).
+- **Promote beyond `MAX_CONTROLLERS`** → server rejects, re-syncs the owner's UI.
+- **`everyone` mode** → the `controllers` set is still maintained (so flipping to `host-only`
+  keeps the chosen co-hosts), it just isn't enforced while in `everyone`.
+- **peerId spoofing** → unchanged accepted limitation (see `docs/KNOWN_LIMITATIONS.md`);
+  co-host doesn't widen it materially (still bounded to a temporary room).
+
+## 7. Scale: the "4 of 510 people" part — read this
+
+The role change above is moderate. **Putting 510 people in one room is a separate, larger
+problem** and should be its own track:
+
+- `MAX_PEERS_PER_ROOM` is **25** today. 510 needs a large raise + load testing.
+- **The real bottleneck at scale is heartbeat fan-out, not control events.** Every peer
+  heartbeats and the relay broadcasts each to all peers → O(N²) per interval. At 510 that's
+  ~510×509 / 15s ≈ **17k msg/s just for heartbeats** — the scaling wall.
+- **Co-host actually *helps* the control-event side:** in `host-only` mode only the few
+  controllers emit play/pause/seek, so event *sources* drop from N to K (e.g. 4). Restricting
+  who can drive is synergistic with big rooms.
+- Large rooms therefore need (independent of co-host):
+  - **Heartbeat fan-out reduction** — e.g. only relay controller/owner heartbeats to everyone,
+    relay guest heartbeats only to the owner/controllers (for the UI), or server-side
+    aggregation into periodic snapshots instead of per-peer relay.
+  - **`ROOM_DATA` payload trimming** — a 510-entry peer list is large; send counts + controller
+    details, lazy-load the full roster.
+  - Possibly the **socket.io Redis adapter** for horizontal scaling, and broadcast tuning.
+
+## 8. Effort estimate
+- **Co-host roles** (server gate generalization + `SET_PEER_ROLE` + owner-leave fallback +
+  client gates + promote UI + i18n), at the current ≤25-peer scale: **~3–4 dev days** (same
+  shape as host-control itself — mostly generalizing host→controller-set).
+- **Large-room scaling (510)**: a **separate ~1–2 week** track (heartbeat redesign + payload
+  trimming + cap raise + load testing), independent of co-host. Recommend shipping co-host at
+  the current cap first, then scaling rooms as its own project.
+
+## 9. Suggested sequencing
+1. `CAPABILITIES.CO_HOST` + `controllers`/`ownerPeerId` in room state + `ROOM_DATA` (additive).
+2. Server `SET_PEER_ROLE` + gate generalization + owner-leave fallback + WS tests.
+3. Background: controller-set membership in both gates + `amOwner`/`amController`.
+4. Popup: promote/demote toggles (owner) + Controller badge + i18n.
+5. (Separate track) large-room scaling.

docs/internal/host-control-mode-EDGECASES.md

@@ -0,0 +1,283 @@
+# Host Control Mode — Branch Overview, Goals & Edge Cases
+
+> **This is the canonical entry-point doc for branch `feature/host-control-mode`.**
+> If you're an agent or contributor picking this up: read this file first, then the
+> implementation plan in [`host-control-mode-plan.md`](./host-control-mode-plan.md).
+> Temporary working doc — delete or fold into permanent docs before merging to `main`.
+>
+> Status legend: 🔴 open / unresolved · 🟡 idea, needs testing · 🟢 decided
+
+---
+
+## 0. Implementation status
+
+All five layers are implemented & pushed (server + background + content + popup + i18n).
+Automated checks green: ESLint, WS integration tests (incl. host-only gate, toggle
+reject, host-leave fallback), content video-finder, locale consistency (15 langs),
+full release verification.
+
+**Still needs real-device testing** — the EC test matrix in §7 (YouTube/Netflix/
+Twitch/Disney+/Jellyfin): involuntary-pause classification (EC-1/EC-5/EC-8), snap-back
+reliability and fight-loops (EC-4), and the desync/resync flow across players. The
+intent classifier (EC-9) and snap-back cooldown are first-pass heuristics tuned by
+reading the code, not yet by watching them behave on each site.
+
+Deferred by decision (see §8): host grace period on disconnect (EC-10).
+
+### Capability detection (forward-compat hook)
+The relay advertises `capabilities: ['host-control']` in `ROOM_DATA`
+(`SERVER_CAPABILITIES` in server, `CAPABILITIES` in shared/constants). The client
+enables host-control UI/behavior only when the flag is present, so the feature
+degrades cleanly on an older relay (absent → off) and old clients ignore the
+field. This is the extensible hook for the planned **co-host** feature (owner
+promotes guests to additional controllers): it will add a `'co-host'` capability
++ events without a protocol bump or breaking older relays/clients. Add new flags
+to `CAPABILITIES` / `SERVER_CAPABILITIES` as features land.
+
+### Pre-test self-audit (fixed)
+- **Popup remote buttons froze for guests** — in host-only a guest's Play/Pause/SYNC
+  click was gated server-side but the button stuck on "Playing"/disabled with no
+  feedback. Now the remote controls are locked (disabled + tooltip) for guests, with
+  backstop guards in the handlers. (popup.js)
+- **Desync dialog could break under strict CSP** — it used `innerHTML` with inline
+  `style=""` attributes, which Netflix/YouTube/Disney+ strip via `style-src`. Rebuilt
+  with the DOM API (CSSOM `.style` is CSP-safe) inside a **Shadow DOM** so page CSS
+  can't restyle/hide it. (content.js)
+- **Live-DVR not detected (EC-15)** — `duration === Infinity` misses Twitch/YouTube
+  live-DVR (finite, sliding duration). Added a `seekable.start(0) > 1` sliding-window
+  heuristic in `hcmIsLive()`. (content.js)
+
+### Pre-test self-audit
+- ~~**EC-4/EC-1 snap-back thrash:**~~ FIXED — implemented the **buffer-aware deferred
+  snap-back** (`hcmDeferredSnapBack`): on an involuntary event, if the player isn't
+  ready (`readyState<3` or seeking) we wait (poll, 8s cap) until it can play, then snap
+  ONCE to the host's re-queried position instead of repeatedly fighting the buffer.
+  Done defensively/player-agnostically — we can't enumerate every site, so this is safe
+  whether a player fires `pause()` or only `waiting`. Aborts if the user goes solo or is
+  no longer a gated guest; single pending poll (no stacking).
+- ~~**Control-mode race at join:**~~ FIXED — `hcmHandleBlocked` now treats `HOST_BLOCKED`
+  as authoritative (adopts host-only/guest role) instead of re-checking local mode,
+  since background only sends it to gated guests.
+- ~~**Dialog/badge text is English-only**~~ FIXED — background resolves the strings
+  via GET_HCM_STRINGS (it has the i18n loader); content fetches them on init with
+  English fallback. 6 new keys (HCM_DIALOG_*/HCM_BADGE_*) across all 15 locales.
+
+---
+
+## 1. What this branch is for
+
+Origin: a GitHub feature request. When watching with larger groups, anyone can pause
+or seek and disrupt everyone else. The requester wants the room creator to optionally
+restrict control to a single **host**, the way Teleparty works — guests who try to
+pause get asked whether they want to pause *only their own* player (and desync), and
+otherwise get snapped back to the room's position.
+
+**Goal:** Add an optional per-room **Host Control Mode**. A room can be switched
+between:
+- **`everyone`** (default, current behavior): anyone can play/pause/seek for the room.
+- **`host-only`**: only the host drives the room. A guest's deliberate play/pause/seek
+  is not broadcast; instead they're snapped back to the room position — unless they
+  explicitly choose to desync (go solo) with a "Resync" escape hatch.
+
+## 2. Trust model (read this before over-engineering)
+
+This is **client-side trust, by design**. It's a watch party, not a security boundary.
+The point is preventing *accidental* and *casual* disruption, not stopping someone
+determined to patch their own extension. We do **not** add auth, tokens, or
+cryptographic host identity. `peerId` is unauthenticated and that's fine here.
+
+(We still gate server-side as the robust chokepoint — see plan — but that's about
+killing spam reliably, not about defeating a hostile client.)
+
+## 3. Scope / non-goals
+
+In scope:
+- Host designation (first joiner = host), mode toggle, host-only gating of all
+  room-moving events, guest snap-back, deliberate-desync flow + resync, host UI.
+
+Explicit non-goals (for this branch):
+- Authenticated / spoof-proof host identity.
+- Persistent host across server restarts (room state is in-memory).
+- Syncing around personalized ad breaks.
+- Host transfer UI (auto-fallback to `everyone` when host leaves; manual transfer
+  is a possible later add).
+
+## 4. Architecture summary
+
+Three-layer gate for room-moving events from a non-host in host-only mode
+(`PLAY`, `PAUSE`, `SEEK`, `FORCE_SYNC_PREPARE`, `FORCE_SYNC_EXECUTE`, `EPISODE_LOBBY`):
+1. **Server** — doesn't relay them (robust chokepoint, kills spam regardless of client).
+2. **Sender (guest)** — doesn't emit; shows confirm dialog / disables host-only buttons.
+3. **Receiver** — drops any that slip through (covers old/buggy/modified clients).
+
+Snap-back reuses the existing `_setSuppress` mechanism (content.js:442) so applying
+the room state programmatically doesn't echo back as a new event. Target position is
+extrapolated from the host's last known state (±1s). Full detail + code hooks in the
+plan doc.
+
+---
+
+## 5. The central challenge
+
+Everything hard about this feature reduces to **one question** (see EC-9):
+
+> How do we reliably tell a **deliberate** guest pause/seek from an **involuntary**
+> player/browser event (buffering, ads, tab throttling, source swaps, DRM hiccups)?
+
+If we get this wrong, guests get spammed with desync dialogs and snap-back loops for
+things they never did. The host/role plumbing is the easy part; this classifier is the
+real work. **Design the intent-classifier before writing the gate.**
+
+---
+
+## 6. Edge cases
+
+### EC-1 🔴 Buffering / loading fires a `pause` event
+content.js listens to `play`/`pause`/`seeked`/`loadeddata` only (content.js:1000-1003),
+not `waiting`/`stalled`. Pure HTML5 buffering fires `waiting` → harmless. But custom
+players (Netflix/YouTube/Twitch/JW) often call `video.pause()` during buffering/ads →
+real `pause` → guest gate would mis-classify as deliberate. Sub-cases: (a) initial load
+sits paused, no event, fine; (b) mid-stream stall, player-dependent; (c) seek-induced
+re-buffering may outlast the suppress window and leak. Mitigation: `isBuffering` flag
+from `waiting`/`playing`, or grace window; in host-only the guest's own state is
+irrelevant so just ignore involuntary pauses and let catch-up logic (content.js:489)
+re-sync them.
+
+### EC-2 🟢 Force-Sync / Episode-Lobby abuse by guests
+Guest could seek + spam Force-Sync to drag everyone, or spam Episode-Lobby to pause
+everyone. Decision: host-only blocks guest *initiation* of `FORCE_SYNC_*` and
+`EPISODE_LOBBY`; guests may only respond (`FORCE_SYNC_ACK`, `EPISODE_READY`). Guests'
+legitimate path is the personal "Resync" button.
+
+### EC-3 🟢 Host leaves the room
+Fall back to `controlMode = 'everyone'`, broadcast `CONTROL_MODE`. Never a stuck locked
+room. (Auto-promote next peer deferred.)
+
+### EC-4 🔴 Snap-back fight loop (pause/play/skip back/pause/play)
+Mashing controls or a janky player → each snap-back may emit events → ping-pong.
+Mitigation: cooldown (~600ms) after snap-back; ensure snap-back runs fully under
+suppress. Also: if target is unreachable (seek past buffered range), retry K times then
+give up — no infinite loop.
+
+### EC-5 🔴 Ad breaks (YouTube/Twitch/…)
+Mid-roll ads pause/swap the media element, differ per peer → desync is unavoidable and
+must NOT spam the dialog. Probably covered by EC-1 buffering grace; flag for explicit
+testing.
+
+### EC-6 🟡 Snap-back target accuracy
+No continuous room clock; extrapolate from host's `currentTime` + `lastHeartbeat`
+(±1s, worse if stale). The follow-up host correction must also be suppressed so it
+doesn't read as guest input.
+
+### EC-7 🟢 Old / buggy / modified guest client
+Covered by receiver-side + server-side gates.
+
+### EC-8 🔴 Tab throttling / background tab
+Backgrounding throttles timers and may pause media. There's existing
+`visibilityGraceUntil` handling for seeks (content.js:892). Confirm a
+background-induced pause isn't treated as deliberate in host-only; reuse the grace flag.
+
+### EC-9 🔴 What counts as "deliberate" — the central unresolved question
+Collapses EC-1/EC-5/EC-8. Candidate signals: `readyState`/`networkState`/`video.seeking`
+at event time; recent `waiting`; recent user gesture (`navigator.userActivation`,
+keydown/click); visibility/focus. Build one shared **intent-classifier** helper in
+content.js that all host-only gating flows through.
+
+### EC-10 🔴 Host brief disconnect / reconnect (network blip)
+Host's wifi drops for 3s and reconnects. With "host leaves → fallback to everyone",
+a blip would silently unlock the room and demote the host (peerId persists in
+chrome.storage so they rejoin with the same id, but the server already cleared
+`hostPeerId`). Mitigation idea: short **host grace period** (e.g. keep `hostPeerId`
+reserved for ~30s after disconnect; if the same peerId rejoins, restore host + mode).
+Needs the server reaper (server:644) and `removePeerFromRoom` (server:168) to cooperate.
+
+### EC-11 🔴 New guest joins mid-session in host-only mode
+On join they must (a) immediately sync to the host's current position without the host
+doing anything, and (b) see they're a guest in the UI. ROOM_DATA already carries peers;
+add `hostPeerId`/`controlMode` so a fresh client knows its role instantly. Verify the
+existing "newcomer syncs without waiting" path (content.js:542) still fires.
+
+### EC-12 🔴 Desync semantics — what does "solo" actually mean?
+When a guest chooses "pause only me", do they (a) fully ignore all subsequent host
+events until they Resync, or (b) keep receiving but not auto-applying? Define clearly.
+Proposed: full solo — ignore host play/pause/seek while desynced; Resync re-attaches and
+snaps to current host position. Also: what state does Resync land them in if the host is
+currently paused vs playing?
+
+### EC-13 🔴 Race: host flips to host-only exactly as a guest pauses
+Event ordering between `SET_CONTROL_MODE`/`CONTROL_MODE` and an in-flight guest `PAUSE`.
+The `seq` ordering helps, but define the tie-break. Likely: server is authoritative —
+once it has `host-only`, it drops the guest event regardless of client-side timing.
+
+### EC-14 🟡 Volume / mute / audio-options must NOT be gated
+Those are per-peer, not room control. The gate must target only play/pause/seek +
+forcesync/episode — not `PEER_STATUS` volume/mute fields. Easy to over-block; add a test.
+
+### EC-15 🔴 Live streams (Twitch live, live DVR)
+"Room timestamp" is fuzzy on live edge; seeking semantics differ. Decide whether
+host-only even makes sense for live, or degrade gracefully. Low priority but log it.
+
+### EC-16 🟡 Host's own involuntary events still drive the room
+If the host buffers and the player auto-pauses, that pause is "allowed" and pauses
+everyone. That's existing behavior, but in host-only it means the host's buffering
+stalls the whole room. Acceptable? Probably yes (host is authoritative), but note it.
+
+### EC-17 🟡 Server restart drops room state
+`hostPeerId`/`controlMode` are in-memory. After a server restart, whoever rejoins first
+becomes the new host and mode resets to `everyone`. Acceptable for now (non-goal), but
+document so it's not a surprise.
+
+### EC-18 🟡 Dialog dismissed without choosing
+Guest clicks away / presses Esc on the desync prompt. Default = treat as "No" → snap
+back. Make sure an un-answered dialog can't leave them in limbo (paused + not desynced +
+no dialog).
+
+### EC-19 🟡 Multiple video elements / element swap (SPA, ad → content)
+Players that swap the `<video>` element mid-session: re-attach handlers (content.js
+already re-binds on `loadeddata`) and make sure host-only gating follows the new element.
+
+### EC-20 🟡 Peer list shape (object vs legacy string)
+Throughout background.js peers may be objects or bare peerId strings
+(`typeof p === 'object' ? p.peerId : p`). All new `hostPeerId` comparisons must handle
+both forms, or we get a host that's never recognized.
+
+### EC-21 🟡 Mode toggle spam / rate limiting
+Host hammering the toggle → many `SET_CONTROL_MODE`. Covered by existing
+`checkEventRate` (server), but debounce in the UI and ignore no-op transitions.
+
+---
+
+## 7. Test matrix (fill in during dev)
+
+| Player            | Buffer→`pause`? | Ad behavior | Snap-back works? | Element swap? | Notes |
+|-------------------|-----------------|-------------|------------------|---------------|-------|
+| Generic HTML5     |                 |             |                  |               |       |
+| YouTube           |                 |             |                  |               |       |
+| Netflix           |                 |             |                  |               |       |
+| Twitch (VOD)      |                 |             |                  |               |       |
+| Twitch (live)     |                 |             |                  |               |       |
+| Disney+ / DRM     |                 |             |                  |               |       |
+| Jellyfin / Emby   |                 |             |                  |               |       |
+
+## 8. Decisions (audited)
+- [x] **Intent-classifier (EC-9):** A `pause`/`seek` is **involuntary** if ANY of:
+  `readyState < 3`, `video.seeking`, a `waiting` fired < ~1500ms ago (`isBuffering`
+  flag), inside `visibilityGraceUntil`, OR no own-tracked user gesture
+  (`Date.now() - lastUserGestureAt < 1000`, via capturing keydown/pointerdown — do
+  NOT use sticky `navigator.userActivation.hasBeenActive`). Bias: only *clearly*
+  involuntary is ignored; everything else = deliberate. **Note:** in host-only the
+  guest never broadcasts anyway, so this only decides dialog-vs-silent — a UX call,
+  not a room-integrity call. Start simple, tune later.
+- [x] **Host grace on disconnect (EC-10): NOT in v1.** Immediate fallback to
+  `everyone` (EC-3). A grace window risks a multi-second hard-lock if the host never
+  returns. Revisit as polish once the core flow works.
+- [x] **Desync semantics (EC-12): full solo.** Ignore host play/pause/seek while
+  desynced; Resync snaps to host position + adopts host play/pause state. Desync
+  auto-clears on new media/episode. Requires a persistent, obvious "You are desynced"
+  UI.
+- [x] **Snap-back cooldown (EC-4): until-settled, not fixed.** Suppress re-trigger
+  until `readyState>=3 && playing && |Δt|<tol`, hard-cap ~1500ms. Retry target up to
+  3×, then give up (no infinite loop).
+- [x] **Live streams (EC-15): degrade.** Disable the gate when
+  `video.duration === Infinity`. Caveat: live-DVR may report finite duration and slip
+  through — acceptable for v1.

docs/internal/host-control-mode-TESTING.md

@@ -0,0 +1,83 @@
+# Host Control Mode — Beta Testing Guide
+
+> Temporary doc for branch `feature/host-control-mode`. Remove before merge.
+> The feature needs the **server** half too — the official relay
+> (`wss://syncserver.koalastuff.net`) doesn't run it yet, so test against a beta
+> server first.
+
+## 1. Run the beta relay (Docker)
+
+The branch publishes the server image to GHCR under non-production tags
+(`:beta` = newest branch build, `:sha-<commit>` = immutable pin). `:latest` is
+never touched.
+
+```bash
+# Log in (the package is private → PAT with read:packages)
+echo "$GHCR_PAT" | docker login ghcr.io -u <your-gh-user> --password-stdin
+
+# Pull + (re)create — NOTE: `docker restart` does NOT pick up a new image,
+# you must remove and re-run (or use compose / Watchtower).
+docker pull ghcr.io/shik3i/koalasync:beta
+docker rm -f koala-beta 2>/dev/null || true
+docker run -d --name koala-beta -p 3000:3000 \
+  -e SERVER_SALT='choose-your-own-salt' \
+  ghcr.io/shik3i/koalasync:beta
+```
+
+To always run the newest beta automatically, point **Watchtower** at the
+container — it does the pull → recreate whenever `:beta` moves.
+
+The `OFFICIAL_SERVER_TOKEN` is baked into `shared/constants.js`, so no token env
+is needed. Set `SERVER_SALT` (used for room-password hashing).
+
+## 2. Connect the extension to it
+
+⚠️ The client **force-upgrades `ws://` to `wss://` for any non-localhost host**
+(see background.js "Upgraded to wss:// for remote host"). So a bare
+`ws://your-server:3000` will fail without TLS. Two options:
+
+- **Quick (no TLS):** SSH-tunnel the port so it counts as local:
+  ```bash
+  ssh -L 3000:localhost:3000 your-beta-server
+  ```
+  then in the popup → **Manual Connect / Advanced → Custom →** `ws://localhost:3000`.
+- **Proper:** put the container behind a TLS reverse proxy (Caddy does automatic
+  HTTPS) → `wss://beta.yourdomain`.
+
+Then create/join a room.
+
+## 3. ⚠️ Use two *new* clients
+
+Test with **two browser profiles both running this branch build** (load unpacked
+from `extension/`, or install the built zip). A stock release client as a guest
+will be correctly gated by the server but has none of the content-side code, so
+it silently desyncs with no dialog/snap-back — that's expected degradation, not a
+bug, but it looks like one during testing.
+
+## 4. Verification checklist
+
+| # | Step | Expect |
+|---|------|--------|
+| 1 | Create a room (host) | Host Control card shows **Host** + the toggle |
+| 2 | Second profile joins | Guest sees no card while mode is "everyone" |
+| 3 | Host enables "Only I can control" | Guest's Play/Pause/SYNC buttons lock; card shows **Guest** |
+| 4 | Guest presses pause/space on the video | Brief flicker, snaps back to host position |
+| 5 | Guest pauses again | Dialog: "Stay in sync" / "Watch on my own" |
+| 6 | Guest → "Watch on my own" | Persistent "Solo" badge; host's peer list shows **Solo** |
+| 7 | Guest → "Resync" | Snaps back to host; Solo badge clears on both sides |
+| 8 | Guest tries Force-Sync / seek spam | Nothing propagates to the room |
+| 9 | Host disables host-only | Card hides for guest; controls unlock |
+| 10 | Host leaves the room | Room falls back to "everyone"; a remaining peer becomes host |
+| 11 | Reload the guest's page while desynced | Still shows Solo (state survives reload) |
+| 12 | Switch the popup language | Dialog/badge text is localized |
+
+## 5. Capability detection
+
+The relay advertises `capabilities: ['host-control']` in `ROOM_DATA`. The client
+only enables the feature when that flag is present, so:
+- against this beta server → feature on;
+- against the old official server → feature cleanly hidden (no errors).
+
+This is the extensible hook for the planned **co-host** feature (owner promotes
+guests to additional controllers) — it'll add a `'co-host'` capability + events
+without breaking older relays/clients.

docs/internal/host-control-mode-plan.md

@@ -0,0 +1,122 @@
+# Host Control Mode — Implementierungsplan
+
+Branch: `feature/host-control-mode`
+Issue: GitHub feature request (wasserrutschentester) — nur Host darf den Raum steuern; Gäste werden zurückgesnappt oder gehen bewusst in Desync.
+
+## Ziel
+
+Ein Raum kann zwischen zwei Modi umgeschaltet werden:
+- **`everyone`** (Default, heutiges Verhalten): jeder kann play/pause/seek für alle auslösen.
+- **`host-only`**: nur der Host steuert den Raum. Pause/Seek eines Gasts wird **nicht** gebroadcastet; stattdessen snappt die eigene Extension den Gast zurück auf den Raum-Zustand — es sei denn, der Gast entscheidet sich bewusst für Desync.
+
+Trust-Modell: client-seitig durchgesetzt. Kein Token, keine Auth. Es geht um versehentliches Stören, nicht um Angriffsschutz.
+
+---
+
+## Datenmodell
+
+### Server (`server/index.js`, Room-Objekt ~Z.331)
+Room bekommt zwei neue Felder:
+```js
+room = {
+  ...,
+  hostPeerId: peerId,        // gesetzt beim Anlegen = erster Joiner
+  controlMode: 'everyone',   // 'everyone' | 'host-only'
+}
+```
+- In `ROOM_DATA` (~Z.418) mitschicken: `hostPeerId`, `controlMode`.
+- Neues Event `SET_CONTROL_MODE` (siehe unten): nur akzeptieren, wenn `senderPeerId === room.hostPeerId`. Server setzt `room.controlMode`, broadcastet die Änderung an alle.
+- **Host-Migration:** in `removePeerFromRoom` (~Z.168) — wenn der gehende Peer `hostPeerId` war: entweder neuen Host bestimmen (nächster Peer) **oder** `controlMode` auf `everyone` zurückfallen lassen. → Entscheidung: **Fallback auf `everyone`** (simpel, nie verwaister gesperrter Raum). Optional später: Host-Transfer-Button.
+
+### Shared Constants (`shared/constants.js`)
+Neue Events im `EVENTS`-Objekt:
+```js
+SET_CONTROL_MODE: "set_control_mode",   // Client->Server: Host ändert Modus
+CONTROL_MODE: "control_mode",            // Server->Client: Modus geändert { controlMode, hostPeerId }
+```
+⚠️ Danach `node scripts/build-extension.cjs` laufen lassen (Single Source of Truth propagieren). Ggf. `PROTOCOL_VERSION` bumpen — **nein, nur wenn alte Clients brechen würden**. Da alles additiv ist und alte Clients die neuen Felder/Events einfach ignorieren, ist KEIN Protokoll-Bump nötig. (Alter Client in host-only-Raum kennt den Modus nicht und sendet weiter → Host-Extensions ignorieren fremde Events nicht... → siehe Edge Case 7. Evtl. doch Bump erwägen.)
+
+### Extension State (`background.js`)
+```js
+let controlMode = 'everyone';
+let hostPeerId = null;
+// abgeleitet: const amHost = () => hostPeerId === peerId;
+```
+Aus `ROOM_DATA` / `CONTROL_MODE` befüllen, in `chrome.storage.session` persistieren (wie `currentRoom`).
+
+---
+
+## Implementierung nach Schichten
+
+### 1. Server (`server/index.js`)
+- [ ] Room-Objekt um `hostPeerId` + `controlMode` erweitern (~Z.331).
+- [ ] `ROOM_DATA`-Payload erweitern (~Z.418).
+- [ ] Handler `SET_CONTROL_MODE`: validieren (Host-Check + Wert in {everyone, host-only}), setzen, `CONTROL_MODE` an Raum broadcasten.
+- [ ] Host-Migration in `removePeerFromRoom`: Fallback auf `everyone` + neues `CONTROL_MODE` broadcasten, wenn Host geht.
+- [ ] `SET_CONTROL_MODE` in die `relayEvents`-Liste? **Nein** — eigener Handler, da Sonderlogik + Host-Check. (relayEvents broadcastet blind.)
+
+### 2. Shared / Build
+- [ ] `EVENTS.SET_CONTROL_MODE`, `EVENTS.CONTROL_MODE` ergänzen.
+- [ ] `node scripts/build-extension.cjs`.
+
+### 3. background.js (Gast-Logik = Kern)
+- [ ] `controlMode` / `hostPeerId` aus `ROOM_DATA` (~Z.875) und neuem `CONTROL_MODE`-Case übernehmen + persistieren + an Popup/Content pushen.
+- [ ] **Emit-Gate** im SEND-Pfad (~Z.1786): bei `host-only && !amHost()` und action ∈ {play, pause, seek}:
+      - NICHT `emit`en.
+      - Stattdessen Content-Script anweisen: "snap back" ODER Desync-Confirm anzeigen.
+- [ ] **Snap-Back-Zielzeit berechnen:** aus Host-Peer-State (`playbackState`, `currentTime`, `lastHeartbeat`) extrapolieren:
+      `targetTime = host.currentTime + (host.playbackState==='playing' ? (now - host.lastHeartbeat)/1000 : 0)`.
+      Genauigkeit ~±1s, für Watchparty ok. (Force-Sync-Maschinerie als Referenz für Ziel-Zeit-Koordination.)
+- [ ] Nachricht an content.js: `{ type: 'HOST_BLOCK', action, targetTime, hostPlaybackState }`.
+
+### 4. content.js (Player-Reaktion + Dialog)
+- [ ] Handler für `HOST_BLOCK`: Confirm-Dialog im Player-Overlay rendern:
+      "Pause only your own player and desync from the group? [Yes] [No]".
+      - **No** (Default): Player via bestehende `_setSuppress`-Mechanik ([content.js:442](../extension/content.js:442)) wieder in Raum-Zustand zwingen (play + seek auf targetTime). Suppress verhindert Re-Broadcast.
+      - **Yes:** lokal pausiert lassen, `isDesynced = true` setzen, dezenten "Desynced — Resync"-Button zeigen.
+- [ ] "Resync"-Button → snappt zurück auf aktuelle Raum-Zeit, `isDesynced = false`.
+- [ ] **Loop-Schutz:** nach einer Snap-Back-Aktion kurzes Cooldown-Fenster (z.B. 600ms), in dem weitere lokale pause/seek-Events nicht erneut den Dialog triggern (verhindert pause→play→pause-Pingpong).
+
+### 5. popup (Host-UI)
+- [ ] Host-Toggle "Only I can control" (nur sichtbar wenn `amHost()`), sendet `SET_CONTROL_MODE`.
+- [ ] Rollen-Badge: "Host" / "Guest" + aktueller Modus.
+- [ ] Gast-Hinweis wenn host-only aktiv: "The host controls playback".
+- [ ] i18n-Keys in `extension/_locales` / `locales` für ~15 Sprachen.
+
+---
+
+## Edge Cases (Test-Checkliste)
+
+1. **Pause nicht verhinderbar, nur revidierbar** → kurzer Flicker (~½s) beim Gast ist erwartet/akzeptabel.
+2. **Snap-Back-Zielzeit** aus Heartbeat extrapoliert, ±1s. Bei stark veraltetem Host-State (kein Heartbeat) → letzten bekannten Wert nehmen.
+3. **Kampf-Loop pause/play/skip back/pause/play** → Cooldown-Fenster nach Snap-Back. Testen mit aggressivem Mashing.
+4. **Desync-Escape:** Gast kann bewusst pausieren (Klo/Telefon) → "Yes" → solo, dann Resync.
+5. **Host verlässt Raum** → Fallback auf `everyone`, alle bekommen `CONTROL_MODE`-Update. Testen: Host schließt Tab / Disconnect / Netzabbruch.
+6. **host-only + Episode-Auto-Sync / Force-Sync** (server/index.js:503-516): **Gast darf NICHT initiieren.** Force-Sync trägt eine `targetTime` und zwingt ALLE darauf (background.js:1261) — ein Gast könnte seeken → Force-Sync spammen und damit host-only komplett aushebeln. Episode-Lobby pausiert ebenfalls alle. → Im host-only-Modus dürfen `FORCE_SYNC_PREPARE`/`FORCE_SYNC_EXECUTE` und `EPISODE_LOBBY` nur vom Host **initiiert** werden. Gäste dürfen weiterhin nur **reagieren**: `FORCE_SYNC_ACK`, `EPISODE_READY`. Gäste brauchen Force-Sync nicht — ihr legitimer Fall ist der "Resync"-Button (snappt nur sie selbst, nicht alle).
+7. **Alter Client (ohne Feature) in host-only-Raum** → kennt Modus nicht, sendet weiter pause/seek → andere Extensions wenden es an. Mitigation: Empfänger-seitiges Gate (host-only-Clients ignorieren play/pause/seek von Nicht-Host) ODER `MIN_VERSION`/Protokoll-Bump. → **Empfehlung: zusätzlich Empfänger-seitig filtern** (robuster als nur Sender-Gate).
+8. **Seek getrennt von Pause** → host-only blockt auch Gast-Seeks, nicht nur Pausen.
+9. **Mehrere Tabs / Multi-Peer mit gleicher peerId** (Dedup, server:381) → Host-Identität bleibt an peerId hängen, ok.
+10. **DAU-Verwirrung** "warum kann ich nicht mehr pausieren?" → klare UI-Botschaft + der Desync-Dialog erklärt sich selbst.
+
+## Architektur-Entscheidung zu Edge Case 7 (wichtig)
+Wir setzen das Gate **doppelt** und über **alle raum-verschiebenden Events**, nicht nur play/pause/seek:
+Geblockte Initiierungen für Nicht-Host im host-only-Modus:
+`PLAY`, `PAUSE`, `SEEK`, `FORCE_SYNC_PREPARE`, `FORCE_SYNC_EXECUTE`, `EPISODE_LOBBY`.
+Weiterhin erlaubt für Gäste (reine Reaktion, verschiebt niemanden): `FORCE_SYNC_ACK`, `EPISODE_READY`, `PEER_STATUS`, `PING`/`PONG`.
+
+- **Sender-seitig** (Gast sendet erst gar nicht) → saubere UX, Confirm-Dialog bei play/pause/seek; Force-Sync-/Episode-Lobby-Buttons im Gast-UI deaktiviert/ausgeblendet.
+- **Empfänger-seitig** (in `handleServerEvent`, background.js:969 + Force-Sync-/Episode-Cases): wenn `host-only` und `data.senderId !== hostPeerId` → Event verwerfen (nicht an Content routen, keine State-Mutation).
+So sind auch alte/buggy/manipulierte Clients abgedeckt, ohne harten Protokoll-Bump.
+
+Optional zusätzlich **server-seitig** in den `relayEvents` (server/index.js:445): im host-only-Modus Initiierungs-Events von Nicht-Host gar nicht erst relayen. Spart Traffic + deckt alles zentral ab. Empfehlenswert, da der Server `hostPeerId`/`controlMode` ohnehin kennt.
+
+---
+
+## Reihenfolge der Umsetzung (kleine, testbare Schritte)
+1. Constants + Build (Events da, nichts kaputt).
+2. Server: hostPeerId/controlMode + ROOM_DATA + SET_CONTROL_MODE + Migration.
+3. background.js: State übernehmen + Empfänger-seitiges Gate (Edge 7) — testbar ohne UI.
+4. background.js: Sender-seitiges Gate + Snap-Back-Zielzeit.
+5. content.js: Snap-Back-Apply + Confirm-Dialog + Loop-Cooldown.
+6. popup: Host-Toggle + Badge + i18n.
+7. Durchtesten der Edge-Case-Liste auf YT / Netflix / generischem HTML5-Player.