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

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.