From 41773d0fef47222a6c283bd0f0b0c06d0b6bdcfd Mon Sep 17 00:00:00 2001
From: cottongin <cottongin@users.noreply.github.com>
Date: Fri, 20 Mar 2026 12:47:37 -0400
Subject: [PATCH] Add implementation plan for overlay manager and player list

8 tasks covering: state machine, WebSocket client extraction, room code
display component, audio controller (restart fix), player list, debug
dashboard, HTML integration, and end-to-end verification.

Made-with: Cursor
---
 ...26-03-20-overlay-manager-implementation.md | 1579 +++++++++++++++++
 1 file changed, 1579 insertions(+)
 create mode 100644 docs/plans/2026-03-20-overlay-manager-implementation.md

diff --git a/docs/plans/2026-03-20-overlay-manager-implementation.md b/docs/plans/2026-03-20-overlay-manager-implementation.md
new file mode 100644
index 0000000..52e8ac2
--- /dev/null
+++ b/docs/plans/2026-03-20-overlay-manager-implementation.md
@@ -0,0 +1,1579 @@
+# Overlay Manager & Player List Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Refactor the OBS overlay from a monolithic single-file design to a modular state-machine architecture, fix the audio restart bug, add a player list component, and handle all new shard-based WebSocket events.
+
+**Architecture:** Central `OverlayManager` state machine coordinates registered components (room code display, audio controller, player list) through explicit lifecycle transitions. WebSocket client routes events to the manager. Components implement a standard `activate`/`deactivate`/`update` interface.
+
+**Tech Stack:** Vanilla JS (ES modules), no build step, loaded via `<script type="module">` in OBS browser source.
+
+---
+
+## Reference: Upstream API Event Payloads
+
+These are the WebSocket event payload shapes from `/api/sessions/live` (see `docs/api/websocket.md` in the `jackboxpartypack-gamepicker` repo):
+
+- **`game.added`** `data`: `{ session: { id, is_active, games_played }, game: { id, title, pack_name, min_players, max_players, manually_added, room_code } }`
+- **`room.connected`** `data`: `{ sessionId, gameId, roomCode, appTag, maxPlayers, playerCount, players[], lobbyState, gameState }`
+- **`lobby.player-joined`** `data`: `{ sessionId, gameId, roomCode, playerName, playerCount, players[], maxPlayers }`
+- **`lobby.updated`** `data`: `{ sessionId, gameId, roomCode, lobbyState, gameCanStart, gameIsStarting, playerCount }`
+- **`game.started`** `data`: `{ sessionId, gameId, roomCode, playerCount, players[], maxPlayers }`
+- **`game.ended`** `data`: `{ sessionId, gameId, roomCode, playerCount, players[] }`
+- **`room.disconnected`** `data`: `{ sessionId, gameId, roomCode, reason, finalPlayerCount }`
+- **`session.started`** `data`: `{ session: { id, is_active, created_at, notes } }`
+- **`session.ended`** `data`: `{ session: { id, is_active, games_played } }`
+- **`player-count.updated`** `data`: `{ sessionId, gameId, playerCount, status }`
+- **`vote.received`** `data`: `{ sessionId, game: { id, title, pack_name }, vote: { username, type, timestamp }, totals: { upvotes, downvotes, popularity_score } }`
+
+---
+
+## Task 1: Create `js/state-manager.js` — OverlayManager State Machine
+
+**Files:**
+- Create: `js/state-manager.js`
+
+**Step 1: Create the OverlayManager class**
+
+Create `js/state-manager.js` with the following:
+
+```javascript
+const VALID_STATES = ['idle', 'lobby', 'playing', 'ended', 'disconnected'];
+
+const VALID_TRANSITIONS = {
+  idle:         ['lobby', 'disconnected'],
+  lobby:        ['lobby', 'playing', 'ended', 'idle', 'disconnected'],
+  playing:      ['ended', 'lobby', 'idle', 'disconnected'],
+  ended:        ['idle', 'lobby', 'disconnected'],
+  disconnected: ['idle', 'lobby'],
+};
+
+const OVERRIDE_MODES = { AUTO: 'auto', FORCE_SHOW: 'force_show', FORCE_HIDE: 'force_hide' };
+
+export class OverlayManager {
+  constructor() {
+    this._state = 'idle';
+    this._components = new Map();
+    this._overrides = new Map();
+    this._context = {};
+    this._eventLog = [];
+    this._listeners = new Set();
+    this._endedTimer = null;
+  }
+
+  get state() { return this._state; }
+  get context() { return { ...this._context }; }
+
+  registerComponent(name, component) {
+    this._components.set(name, component);
+    this._overrides.set(name, OVERRIDE_MODES.AUTO);
+  }
+
+  onChange(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  _notify() {
+    for (const fn of this._listeners) {
+      try { fn(this._state, this._context); } catch (e) { console.error('[Manager] Listener error:', e); }
+    }
+  }
+
+  setOverride(componentName, mode) {
+    if (!this._components.has(componentName)) return;
+    if (!Object.values(OVERRIDE_MODES).includes(mode)) return;
+    this._overrides.set(componentName, mode);
+    this._applyOverride(componentName);
+    this._notify();
+  }
+
+  getOverride(componentName) {
+    return this._overrides.get(componentName) || OVERRIDE_MODES.AUTO;
+  }
+
+  _applyOverride(name) {
+    const component = this._components.get(name);
+    const mode = this._overrides.get(name);
+    if (!component) return;
+
+    if (mode === OVERRIDE_MODES.FORCE_SHOW) {
+      component.activate(this._context);
+    } else if (mode === OVERRIDE_MODES.FORCE_HIDE) {
+      component.deactivate();
+    }
+    // AUTO: no action here, state transitions handle it
+  }
+
+  transition(newState, contextUpdates = {}) {
+    if (!VALID_STATES.includes(newState)) {
+      console.error('[Manager] Invalid state:', newState);
+      return;
+    }
+    if (!VALID_TRANSITIONS[this._state]?.includes(newState)) {
+      console.warn(`[Manager] Invalid transition: ${this._state} → ${newState}`);
+      return;
+    }
+
+    const oldState = this._state;
+    const wasLobby = oldState === 'lobby';
+    const isLobby = newState === 'lobby';
+
+    Object.assign(this._context, contextUpdates);
+    this._state = newState;
+
+    if (this._endedTimer) {
+      clearTimeout(this._endedTimer);
+      this._endedTimer = null;
+    }
+
+    if (wasLobby && !isLobby) {
+      this._deactivateAllComponents();
+    } else if (wasLobby && isLobby) {
+      // lobby → lobby (new room code): full reset
+      this._deactivateAllComponents();
+      this._activateAllComponents();
+    } else if (!wasLobby && isLobby) {
+      this._activateAllComponents();
+    }
+
+    if (newState === 'ended') {
+      this._endedTimer = setTimeout(() => {
+        this.transition('idle');
+      }, 2000);
+    }
+
+    console.log(`[Manager] ${oldState} → ${newState}`);
+    this._notify();
+  }
+
+  updateComponents(contextUpdates = {}) {
+    Object.assign(this._context, contextUpdates);
+    for (const [name, component] of this._components) {
+      const mode = this._overrides.get(name);
+      if (mode === OVERRIDE_MODES.AUTO && this._state === 'lobby') {
+        component.update(this._context);
+      } else if (mode === OVERRIDE_MODES.FORCE_SHOW) {
+        component.update(this._context);
+      }
+    }
+    this._notify();
+  }
+
+  _activateAllComponents() {
+    for (const [name, component] of this._components) {
+      const mode = this._overrides.get(name);
+      if (mode === OVERRIDE_MODES.AUTO) {
+        component.activate(this._context);
+      } else if (mode === OVERRIDE_MODES.FORCE_HIDE) {
+        // Respect hide override even during lobby
+      }
+    }
+  }
+
+  _deactivateAllComponents() {
+    for (const [name, component] of this._components) {
+      const mode = this._overrides.get(name);
+      if (mode === OVERRIDE_MODES.AUTO) {
+        component.deactivate();
+      }
+    }
+  }
+
+  logEvent(eventType, data) {
+    const entry = { type: eventType, timestamp: new Date().toISOString(), data };
+    this._eventLog.push(entry);
+    if (this._eventLog.length > 50) this._eventLog.shift();
+    this._notify();
+  }
+
+  getEventLog() { return [...this._eventLog]; }
+
+  getComponentStatuses() {
+    const statuses = {};
+    for (const [name, component] of this._components) {
+      statuses[name] = {
+        status: component.getStatus(),
+        override: this._overrides.get(name),
+      };
+    }
+    return statuses;
+  }
+
+  handleEvent(eventType, data) {
+    this.logEvent(eventType, data);
+
+    switch (eventType) {
+      case 'game.added': {
+        const game = data.game;
+        const roomCode = game?.room_code;
+        if (!roomCode) break;
+        this.transition('lobby', {
+          roomCode,
+          gameTitle: game.title,
+          packName: game.pack_name,
+          maxPlayers: game.max_players,
+          minPlayers: game.min_players,
+          gameId: game.id,
+          sessionId: data.session?.id,
+          players: [],
+          playerCount: 0,
+        });
+        break;
+      }
+      case 'room.connected':
+        this.updateComponents({
+          maxPlayers: data.maxPlayers,
+          playerCount: data.playerCount,
+          players: data.players || [],
+          lobbyState: data.lobbyState,
+          gameState: data.gameState,
+          appTag: data.appTag,
+        });
+        if (this._state === 'idle' || this._state === 'ended') {
+          this.transition('lobby', {
+            roomCode: data.roomCode,
+            maxPlayers: data.maxPlayers,
+            playerCount: data.playerCount,
+            players: data.players || [],
+          });
+        }
+        break;
+      case 'lobby.player-joined':
+        this.updateComponents({
+          players: data.players || [],
+          playerCount: data.playerCount,
+          maxPlayers: data.maxPlayers,
+          lastJoinedPlayer: data.playerName,
+        });
+        break;
+      case 'lobby.updated':
+        this.updateComponents({
+          lobbyState: data.lobbyState,
+          playerCount: data.playerCount,
+        });
+        break;
+      case 'game.started':
+        this.transition('playing', {
+          playerCount: data.playerCount,
+          players: data.players || [],
+        });
+        break;
+      case 'game.ended':
+        this.transition('ended', {
+          playerCount: data.playerCount,
+          players: data.players || [],
+        });
+        break;
+      case 'room.disconnected':
+        this.transition('idle', {
+          disconnectReason: data.reason,
+        });
+        break;
+      case 'session.started':
+        this.updateComponents({
+          sessionId: data.session?.id,
+        });
+        break;
+      case 'session.ended':
+        this.transition('idle', {
+          sessionId: null,
+          roomCode: null,
+          players: [],
+          playerCount: 0,
+        });
+        break;
+      case 'player-count.updated':
+        this.updateComponents({
+          playerCount: data.playerCount,
+        });
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+export { OVERRIDE_MODES };
+```
+
+**Step 2: Verify module loads**
+
+Open the overlay HTML in a browser, open DevTools console, and run:
+```javascript
+import('./js/state-manager.js').then(m => { window._sm = m; console.log('loaded', m); });
+```
+Expected: Module loads without errors.
+
+**Step 3: Commit**
+
+```bash
+git add js/state-manager.js
+git commit -m "feat: add OverlayManager state machine module"
+```
+
+---
+
+## Task 2: Create `js/websocket-client.js` — Extract WebSocket Logic
+
+**Files:**
+- Create: `js/websocket-client.js`
+- Reference: `optimized-controls.html:996-1344` (current inline WebSocket code)
+
+**Step 1: Create the WebSocketClient class**
+
+Extract the auth, connection, reconnection, and heartbeat logic from `optimized-controls.html` lines 996-1344 into `js/websocket-client.js`:
+
+```javascript
+export class WebSocketClient {
+  constructor({ onStatusChange, onEvent, onSessionSubscribed }) {
+    this._ws = null;
+    this._jwtToken = null;
+    this._heartbeatInterval = null;
+    this._reconnectTimeout = null;
+    this._reconnectDelay = 1000;
+    this._maxReconnectDelay = 30000;
+    this._intentionalDisconnect = false;
+    this._apiUrl = '';
+    this._apiKey = '';
+    this._onStatusChange = onStatusChange || (() => {});
+    this._onEvent = onEvent || (() => {});
+    this._onSessionSubscribed = onSessionSubscribed || (() => {});
+  }
+
+  get isConnected() {
+    return this._ws && this._ws.readyState === WebSocket.OPEN;
+  }
+
+  async connect(apiUrl, apiKey) {
+    this._apiUrl = apiUrl.replace(/\/+$/, '');
+    this._apiKey = apiKey;
+    this._intentionalDisconnect = false;
+
+    if (!this._apiUrl || !this._apiKey) {
+      this._onStatusChange('error', 'API URL and Key are required');
+      return;
+    }
+
+    this._onStatusChange('connecting', 'Authenticating...');
+
+    try {
+      const response = await fetch(this._apiUrl + '/api/auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ key: this._apiKey }),
+      });
+
+      if (!response.ok) {
+        const errData = await response.json().catch(() => ({}));
+        this._onStatusChange('error', 'Auth failed: ' + (errData.error || response.statusText));
+        return;
+      }
+
+      const data = await response.json();
+      this._jwtToken = data.token;
+
+      if (!this._jwtToken) {
+        this._onStatusChange('error', 'No token in auth response');
+        return;
+      }
+
+      this._onStatusChange('connecting', 'Connecting WebSocket...');
+      this._connectWebSocket();
+    } catch (err) {
+      console.error('[WSClient] Auth error:', err);
+      this._onStatusChange('error', 'Auth error: ' + err.message);
+    }
+  }
+
+  disconnect() {
+    this._intentionalDisconnect = true;
+    if (this._reconnectTimeout) {
+      clearTimeout(this._reconnectTimeout);
+      this._reconnectTimeout = null;
+    }
+    this._stopHeartbeat();
+    if (this._ws) {
+      this._ws.close();
+      this._ws = null;
+    }
+    this._jwtToken = null;
+    this._onStatusChange('disconnected', 'Disconnected');
+  }
+
+  _connectWebSocket() {
+    const wsUrl = this._apiUrl.replace(/^http/, 'ws') + '/api/sessions/live';
+
+    try {
+      this._ws = new WebSocket(wsUrl);
+    } catch (err) {
+      this._onStatusChange('error', 'WebSocket error: ' + err.message);
+      return;
+    }
+
+    this._ws.addEventListener('open', () => {
+      console.log('[WSClient] Connected, authenticating...');
+      this._onStatusChange('connecting', 'Authenticating via WS...');
+      this._reconnectDelay = 1000;
+      this._ws.send(JSON.stringify({ type: 'auth', token: this._jwtToken }));
+    });
+
+    this._ws.addEventListener('message', (event) => {
+      let message;
+      try {
+        message = JSON.parse(event.data);
+      } catch (e) {
+        console.error('[WSClient] Failed to parse message:', event.data);
+        return;
+      }
+      this._handleMessage(message);
+    });
+
+    this._ws.addEventListener('close', (event) => {
+      console.log('[WSClient] Disconnected, code:', event.code);
+      this._stopHeartbeat();
+
+      if (!this._intentionalDisconnect) {
+        this._onStatusChange('connecting', 'Reconnecting in ' + Math.round(this._reconnectDelay / 1000) + 's...');
+        this._scheduleReconnect();
+      } else {
+        this._onStatusChange('disconnected', 'Disconnected');
+      }
+    });
+
+    this._ws.addEventListener('error', (err) => {
+      console.error('[WSClient] Error:', err);
+    });
+  }
+
+  _handleMessage(message) {
+    switch (message.type) {
+      case 'auth_success':
+        console.log('[WSClient] Authenticated');
+        this._onStatusChange('connected', 'Connected');
+        this._startHeartbeat();
+        this._fetchActiveSessionAndSubscribe();
+        break;
+
+      case 'auth_error':
+        console.error('[WSClient] Auth error:', message.message);
+        this._onStatusChange('error', 'WS auth failed: ' + message.message);
+        this._intentionalDisconnect = true;
+        if (this._ws) this._ws.close();
+        break;
+
+      case 'subscribed':
+        console.log('[WSClient] Subscribed to session:', message.sessionId);
+        this._onStatusChange('connected', 'Connected (session ' + message.sessionId + ')');
+        this._onSessionSubscribed(message.sessionId);
+        break;
+
+      case 'pong':
+        break;
+
+      case 'error':
+        console.error('[WSClient] Server error:', message.message);
+        break;
+
+      default:
+        // All domain events route to the manager
+        if (message.data !== undefined) {
+          this._onEvent(message.type, message.data);
+        } else {
+          console.log('[WSClient] Unhandled message type:', message.type);
+        }
+        break;
+    }
+  }
+
+  async _fetchActiveSessionAndSubscribe() {
+    if (!this._apiUrl || !this._jwtToken) return;
+
+    try {
+      const response = await fetch(this._apiUrl + '/api/sessions/active', {
+        headers: { 'Authorization': 'Bearer ' + this._jwtToken },
+      });
+
+      if (response.ok) {
+        const session = await response.json();
+        if (session && session.id) {
+          console.log('[WSClient] Found active session:', session.id);
+          if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+            this._ws.send(JSON.stringify({ type: 'subscribe', sessionId: session.id }));
+          }
+        } else {
+          console.log('[WSClient] No active session, waiting for session.started');
+        }
+      }
+    } catch (err) {
+      console.error('[WSClient] Error fetching active session:', err);
+    }
+  }
+
+  subscribeToSession(sessionId) {
+    if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+      this._ws.send(JSON.stringify({ type: 'subscribe', sessionId }));
+    }
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    this._heartbeatInterval = setInterval(() => {
+      if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+        this._ws.send(JSON.stringify({ type: 'ping' }));
+      }
+    }, 30000);
+  }
+
+  _stopHeartbeat() {
+    if (this._heartbeatInterval) {
+      clearInterval(this._heartbeatInterval);
+      this._heartbeatInterval = null;
+    }
+  }
+
+  _scheduleReconnect() {
+    if (this._reconnectTimeout) clearTimeout(this._reconnectTimeout);
+
+    this._reconnectTimeout = setTimeout(() => {
+      if (this._apiUrl && this._jwtToken && !this._intentionalDisconnect) {
+        console.log('[WSClient] Attempting reconnect...');
+        this._onStatusChange('connecting', 'Reconnecting...');
+        this._connectWebSocket();
+      }
+      this._reconnectDelay = Math.min(this._reconnectDelay * 2, this._maxReconnectDelay);
+    }, this._reconnectDelay);
+  }
+}
+```
+
+The key difference from existing code: `session.started` is now handled as a domain event (forwarded via `_onEvent`) instead of being handled inline. The WebSocket client auto-subscribes to the session from the event data via the `_onEvent` → `handleEvent` flow in the manager. However, `session.started` needs special handling because it requires a `subscribe` call. Add this to `_handleMessage`:
+
+After the `default` case forwards to `_onEvent`, the caller (bootstrap code) will also listen for `session.started` and call `subscribeToSession`. Alternatively, handle it directly:
+
+In the `_handleMessage` method, add a case before `default`:
+
+```javascript
+      case 'session.started':
+        console.log('[WSClient] Session started:', message.data?.session?.id);
+        if (message.data?.session?.id && this._ws?.readyState === WebSocket.OPEN) {
+          this._ws.send(JSON.stringify({
+            type: 'subscribe',
+            sessionId: message.data.session.id,
+          }));
+        }
+        this._onEvent(message.type, message.data);
+        break;
+```
+
+**Step 2: Verify module loads**
+
+Same browser console check:
+```javascript
+import('./js/websocket-client.js').then(m => { window._wsc = m; console.log('loaded', m); });
+```
+
+**Step 3: Commit**
+
+```bash
+git add js/websocket-client.js
+git commit -m "feat: extract WebSocket client into ES module"
+```
+
+---
+
+## Task 3: Create `js/room-code-display.js` — Extract Room Code Animation
+
+**Files:**
+- Create: `js/room-code-display.js`
+- Reference: `optimized-controls.html:739-873` (applySettings + startAnimation), `optimized-controls.html:886-910` (hideDisplay)
+
+**Step 1: Create the RoomCodeDisplay component**
+
+Extract the animation logic into a component that implements the standard interface. The component reads settings from DOM inputs (same as current behavior) but lifecycle is managed externally.
+
+```javascript
+export class RoomCodeDisplay {
+  constructor() {
+    this._timers = [];
+    this._active = false;
+    this._elements = null;
+    this._inputs = null;
+  }
+
+  init(elements, inputs) {
+    this._elements = elements;
+    this._inputs = inputs;
+  }
+
+  activate(ctx) {
+    this.deactivate();
+    this._active = true;
+
+    if (ctx.roomCode) {
+      const midpoint = Math.ceil(ctx.roomCode.length / 2);
+      this._inputs.code1.value = ctx.roomCode.substring(0, midpoint).toUpperCase();
+      this._inputs.code2.value = ctx.roomCode.substring(midpoint).toUpperCase();
+    }
+
+    this._applySettings();
+    this._startAnimation();
+  }
+
+  deactivate() {
+    this._active = false;
+    this._clearTimers();
+
+    if (this._elements) {
+      const fadeTime = '0.3s';
+      for (const el of [this._elements.header, this._elements.footer, this._elements.codePart1, this._elements.codePart2]) {
+        el.style.transition = `opacity ${fadeTime} ease-out`;
+        el.style.opacity = 0;
+      }
+    }
+  }
+
+  update(ctx) {
+    if (!this._active) return;
+    // If room code changed mid-lobby, restart
+    if (ctx.roomCode) {
+      const midpoint = Math.ceil(ctx.roomCode.length / 2);
+      const first = ctx.roomCode.substring(0, midpoint).toUpperCase();
+      const second = ctx.roomCode.substring(midpoint).toUpperCase();
+      if (first !== this._inputs.code1.value || second !== this._inputs.code2.value) {
+        this.activate(ctx);
+      }
+    }
+  }
+
+  getStatus() {
+    return {
+      active: this._active,
+      roomCode: this._inputs ? (this._inputs.code1.value + this._inputs.code2.value) : '',
+      timersRunning: this._timers.length,
+    };
+  }
+
+  _clearTimers() {
+    this._timers.forEach(t => clearTimeout(t));
+    this._timers = [];
+  }
+
+  _applySettings() {
+    const { header, footer, codePart1, codePart2 } = this._elements;
+    const inp = this._inputs;
+
+    codePart1.textContent = inp.code1.value.toUpperCase();
+    codePart2.textContent = inp.code2.value.toUpperCase();
+    codePart1.style.color = inp.color1.value;
+    codePart2.style.color = inp.color2.value;
+    codePart1.style.transform = `translateY(${inp.offset1.value}px)`;
+    codePart2.style.transform = `translateY(${inp.offset2.value}px)`;
+    codePart1.style.fontSize = `${inp.size.value}px`;
+    codePart2.style.fontSize = `${inp.size.value}px`;
+
+    header.textContent = inp.headerText.value;
+    header.style.color = inp.headerColor.value;
+    header.style.fontSize = `${inp.headerSize.value}px`;
+    header.style.transform = `translateY(${inp.headerOffset.value}px)`;
+
+    footer.textContent = inp.footerText.value;
+    footer.style.color = inp.footerColor.value;
+    footer.style.fontSize = `${inp.footerSize.value}px`;
+    footer.style.transform = `translateY(${inp.footerOffset.value}px)`;
+  }
+
+  _startAnimation() {
+    this._clearTimers();
+    const { header, footer, codePart1, codePart2 } = this._elements;
+    const inp = this._inputs;
+
+    header.style.opacity = 0;
+    footer.style.opacity = 0;
+    codePart1.style.opacity = 0;
+    codePart2.style.opacity = 0;
+
+    const cycleDuration = parseInt(inp.cycle.value) * 1000;
+    const headerAppearDelayMs = parseInt(inp.headerAppearDelay.value) * 1000;
+    const headerAppearDurationMs = parseInt(inp.headerAppearDuration.value) * 1000;
+
+    this._timers.push(setTimeout(() => {
+      header.style.transition = `opacity ${headerAppearDurationMs / 1000}s ease-out`;
+      header.style.opacity = 1;
+      footer.style.transition = `opacity ${headerAppearDurationMs / 1000}s ease-out`;
+      footer.style.opacity = 1;
+    }, headerAppearDelayMs));
+
+    const line1AppearDelayMs = parseInt(inp.line1AppearDelay.value) * 1000;
+    const line1AppearDurationMs = parseInt(inp.line1AppearDuration.value) * 1000;
+    this._timers.push(setTimeout(() => {
+      codePart1.style.transition = `opacity ${line1AppearDurationMs / 1000}s ease-out`;
+      codePart1.style.opacity = 1;
+    }, line1AppearDelayMs));
+
+    const line1HideTimeMs = parseInt(inp.line1HideTime.value) * 1000;
+    const line1HideDurationMs = parseInt(inp.line1HideDuration.value) * 1000;
+    this._timers.push(setTimeout(() => {
+      codePart1.style.transition = `opacity ${line1HideDurationMs / 1000}s ease-out`;
+      codePart1.style.opacity = 0;
+    }, line1HideTimeMs));
+
+    const line2AppearDelayMs = parseInt(inp.line2AppearDelay.value) * 1000;
+    const line2AppearDurationMs = parseInt(inp.line2AppearDuration.value) * 1000;
+    this._timers.push(setTimeout(() => {
+      codePart2.style.transition = `opacity ${line2AppearDurationMs / 1000}s ease-out`;
+      codePart2.style.opacity = 1;
+    }, line2AppearDelayMs));
+
+    const line2HideTimeMs = parseInt(inp.line2HideTime.value) * 1000;
+    const line2HideDurationMs = parseInt(inp.line2HideDuration.value) * 1000;
+    this._timers.push(setTimeout(() => {
+      codePart2.style.transition = `opacity ${line2HideDurationMs / 1000}s ease-out`;
+      codePart2.style.opacity = 0;
+    }, line2HideTimeMs));
+
+    const headerHideTimeMs = parseInt(inp.headerHideTime.value) * 1000;
+    const headerHideDurationMs = parseInt(inp.headerHideDuration.value) * 1000;
+    this._timers.push(setTimeout(() => {
+      header.style.transition = `opacity ${headerHideDurationMs / 1000}s ease-out`;
+      header.style.opacity = 0;
+      footer.style.transition = `opacity ${headerHideDurationMs / 1000}s ease-out`;
+      footer.style.opacity = 0;
+    }, headerHideTimeMs));
+
+    // Restart animation loop
+    this._timers.push(setTimeout(() => {
+      if (this._active) this._startAnimation();
+    }, cycleDuration));
+  }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add js/room-code-display.js
+git commit -m "feat: extract room code display into ES module component"
+```
+
+---
+
+## Task 4: Create `js/audio-controller.js` — Extract Audio Logic
+
+**Files:**
+- Create: `js/audio-controller.js`
+- Reference: `optimized-controls.html:784-793` (play in startAnimation), `optimized-controls.html:857-866` (fade out), `optimized-controls.html:904-905` (stop in hideDisplay)
+
+This is the core of the audio restart bug fix. The current code's audio state gets tangled because `hideDisplay()` pauses and resets the audio, but subsequent `startAnimation()` calls don't reload the source or handle the paused+reset state consistently (especially after the fade-out interval modifies `volume`).
+
+```javascript
+export class AudioController {
+  constructor() {
+    this._active = false;
+    this._audioEl = null;
+    this._inputs = null;
+    this._fadeInterval = null;
+  }
+
+  init(audioElement, inputs) {
+    this._audioEl = audioElement;
+    this._inputs = inputs;
+  }
+
+  activate(ctx) {
+    this.deactivate();
+    this._active = true;
+
+    if (!this._inputs.enabled.checked) return;
+
+    const audio = this._audioEl;
+    // Reload source to ensure clean state
+    audio.src = this._inputs.soundUrl.value;
+    audio.volume = parseFloat(this._inputs.volume.value);
+    audio.loop = true;
+    audio.currentTime = 0;
+    audio.load();
+    audio.play().catch(err => {
+      console.log('[Audio] Playback failed:', err.message);
+    });
+  }
+
+  deactivate() {
+    this._active = false;
+    this._stopFade();
+
+    if (this._audioEl) {
+      this._audioEl.pause();
+      this._audioEl.currentTime = 0;
+      // Restore volume to slider value for next activation
+      if (this._inputs) {
+        this._audioEl.volume = parseFloat(this._inputs.volume.value);
+      }
+    }
+  }
+
+  update(_ctx) {
+    // No in-state updates needed for audio
+  }
+
+  getStatus() {
+    const audio = this._audioEl;
+    return {
+      active: this._active,
+      enabled: this._inputs?.enabled.checked ?? false,
+      playing: audio ? !audio.paused : false,
+      volume: audio ? Math.round(audio.volume * 100) : 0,
+      src: audio?.src || '',
+    };
+  }
+
+  startFadeOut(durationMs) {
+    if (!this._audioEl || this._audioEl.paused) return;
+
+    this._stopFade();
+    const steps = 10;
+    const stepInterval = durationMs / steps;
+    const volumeStep = this._audioEl.volume / steps;
+
+    this._fadeInterval = setInterval(() => {
+      if (this._audioEl.volume > volumeStep) {
+        this._audioEl.volume -= volumeStep;
+      } else {
+        this._audioEl.volume = 0;
+        this._audioEl.pause();
+        this._stopFade();
+      }
+    }, stepInterval);
+  }
+
+  _stopFade() {
+    if (this._fadeInterval) {
+      clearInterval(this._fadeInterval);
+      this._fadeInterval = null;
+    }
+  }
+}
+```
+
+The key fix: `activate()` always calls `deactivate()` first, which stops any in-progress fade, pauses audio, and resets state. Then it reloads the source (`audio.src = ...`, `audio.load()`), restores volume to the slider value, and plays from the beginning. This guarantees clean audio state on every lobby entry.
+
+**Step 2: Commit**
+
+```bash
+git add js/audio-controller.js
+git commit -m "feat: extract audio controller into ES module, fix restart bug"
+```
+
+---
+
+## Task 5: Create `js/player-list.js` — New Player List Component
+
+**Files:**
+- Create: `js/player-list.js`
+
+**Step 1: Create the PlayerList component**
+
+```javascript
+const DEFAULT_MAX_PLAYERS = 8;
+
+export class PlayerList {
+  constructor() {
+    this._active = false;
+    this._container = null;
+    this._inputs = null;
+    this._slots = [];
+    this._players = [];
+    this._maxPlayers = DEFAULT_MAX_PLAYERS;
+    this._animationTimers = [];
+  }
+
+  init(container, inputs, animationTimingInputs) {
+    this._container = container;
+    this._inputs = inputs;
+    this._timingInputs = animationTimingInputs;
+  }
+
+  activate(ctx) {
+    this.deactivate();
+    this._active = true;
+
+    if (!this._inputs.enabled.checked) return;
+
+    this._maxPlayers = ctx.maxPlayers || DEFAULT_MAX_PLAYERS;
+    this._players = ctx.players || [];
+
+    this._buildSlots();
+    this._fillSlots(this._players);
+    this._animateIn();
+  }
+
+  deactivate() {
+    this._active = false;
+    this._clearTimers();
+
+    if (this._container) {
+      this._container.style.transition = 'opacity 0.3s ease-out';
+      this._container.style.opacity = 0;
+      setTimeout(() => {
+        if (!this._active) {
+          this._container.innerHTML = '';
+          this._slots = [];
+          this._players = [];
+        }
+      }, 300);
+    }
+  }
+
+  update(ctx) {
+    if (!this._active || !this._inputs.enabled.checked) return;
+
+    if (ctx.maxPlayers && ctx.maxPlayers !== this._maxPlayers) {
+      this._maxPlayers = ctx.maxPlayers;
+      this._buildSlots();
+      this._fillSlots(ctx.players || this._players);
+      return;
+    }
+
+    if (ctx.players) {
+      const newPlayers = ctx.players.filter(p => !this._players.includes(p));
+      this._players = ctx.players;
+      this._fillSlots(this._players, newPlayers);
+    }
+  }
+
+  getStatus() {
+    return {
+      active: this._active,
+      enabled: this._inputs?.enabled.checked ?? false,
+      playerCount: this._players.length,
+      maxPlayers: this._maxPlayers,
+      players: [...this._players],
+    };
+  }
+
+  _buildSlots() {
+    this._container.innerHTML = '';
+    this._slots = [];
+
+    for (let i = 0; i < this._maxPlayers; i++) {
+      const slot = document.createElement('div');
+      slot.className = 'player-slot';
+      slot.dataset.index = i;
+
+      const number = document.createElement('span');
+      number.className = 'player-slot-number';
+      number.textContent = `${i + 1}.`;
+
+      const name = document.createElement('span');
+      name.className = 'player-slot-name empty';
+      name.textContent = '────────';
+
+      slot.appendChild(number);
+      slot.appendChild(name);
+      this._container.appendChild(slot);
+      this._slots.push({ element: slot, nameEl: name, filled: false });
+    }
+  }
+
+  _fillSlots(players, newlyJoined = []) {
+    for (let i = 0; i < this._slots.length; i++) {
+      const slot = this._slots[i];
+      if (i < players.length) {
+        const playerName = players[i];
+        const isNew = newlyJoined.includes(playerName);
+        slot.nameEl.textContent = playerName;
+        slot.nameEl.classList.remove('empty');
+        slot.nameEl.classList.add('filled');
+        slot.filled = true;
+
+        if (isNew) {
+          slot.nameEl.style.opacity = 0;
+          requestAnimationFrame(() => {
+            slot.nameEl.style.transition = 'opacity 0.4s ease-out';
+            slot.nameEl.style.opacity = 1;
+          });
+        }
+      } else if (slot.filled) {
+        slot.nameEl.textContent = '────────';
+        slot.nameEl.classList.remove('filled');
+        slot.nameEl.classList.add('empty');
+        slot.filled = false;
+      }
+    }
+  }
+
+  _animateIn() {
+    this._container.style.opacity = 0;
+    this._container.style.display = 'flex';
+
+    const headerAppearDelay = parseInt(this._timingInputs.headerAppearDelay.value) * 1000;
+    const headerAppearDuration = parseInt(this._timingInputs.headerAppearDuration.value) * 1000;
+
+    this._animationTimers.push(setTimeout(() => {
+      this._container.style.transition = `opacity ${headerAppearDuration / 1000}s ease-out`;
+      this._container.style.opacity = 1;
+    }, headerAppearDelay));
+  }
+
+  _clearTimers() {
+    this._animationTimers.forEach(t => clearTimeout(t));
+    this._animationTimers = [];
+  }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add js/player-list.js
+git commit -m "feat: add player list component with slot-based display"
+```
+
+---
+
+## Task 6: Create `js/controls.js` — Debug Dashboard & Control Bindings
+
+**Files:**
+- Create: `js/controls.js`
+
+**Step 1: Create the Controls module**
+
+This module handles the debug dashboard, manual overrides, and binds existing settings UI elements. It exports an `initControls` function rather than a class.
+
+```javascript
+import { OVERRIDE_MODES } from './state-manager.js';
+
+const STATE_COLORS = {
+  idle: '#888',
+  lobby: '#4CAF50',
+  playing: '#f0ad4e',
+  ended: '#d9534f',
+  disconnected: '#d9534f',
+};
+
+export function initControls(manager, wsClient, components) {
+  const dashboardEl = document.getElementById('manager-dashboard');
+  if (!dashboardEl) return;
+
+  const stateEl = dashboardEl.querySelector('#manager-state');
+  const roomCodeEl = dashboardEl.querySelector('#manager-room-code');
+  const sessionIdEl = dashboardEl.querySelector('#manager-session-id');
+  const gameTitleEl = dashboardEl.querySelector('#manager-game-title');
+  const playerCountEl = dashboardEl.querySelector('#manager-player-count');
+  const eventLogEl = dashboardEl.querySelector('#manager-event-log');
+
+  // Override toggles
+  for (const name of Object.keys(components)) {
+    const select = dashboardEl.querySelector(`#override-${name}`);
+    if (select) {
+      select.addEventListener('change', () => {
+        manager.setOverride(name, select.value);
+      });
+    }
+  }
+
+  // Update dashboard on state change
+  manager.onChange((state, ctx) => {
+    if (stateEl) {
+      stateEl.textContent = state.toUpperCase();
+      stateEl.style.backgroundColor = STATE_COLORS[state] || '#888';
+    }
+    if (roomCodeEl) roomCodeEl.textContent = ctx.roomCode || '—';
+    if (sessionIdEl) sessionIdEl.textContent = ctx.sessionId || '—';
+    if (gameTitleEl) gameTitleEl.textContent = ctx.gameTitle ? `${ctx.gameTitle} (${ctx.packName || ''})` : '—';
+    if (playerCountEl) {
+      const count = ctx.playerCount ?? 0;
+      const max = ctx.maxPlayers ?? '?';
+      playerCountEl.textContent = `${count} / ${max}`;
+    }
+
+    // Update component status rows
+    const statuses = manager.getComponentStatuses();
+    for (const [name, info] of Object.entries(statuses)) {
+      const statusEl = dashboardEl.querySelector(`#status-${name}`);
+      if (statusEl) {
+        const s = info.status;
+        let text = s.active ? 'Active' : 'Inactive';
+        if (name === 'playerList' && s.active) {
+          text = `Active (${s.playerCount}/${s.maxPlayers})`;
+        }
+        if (name === 'audio' && s.active) {
+          text = s.playing ? 'Playing' : 'Active (muted)';
+        }
+        statusEl.textContent = text;
+      }
+    }
+
+    // Event log
+    if (eventLogEl) {
+      const log = manager.getEventLog();
+      const lastEvents = log.slice(-20);
+      eventLogEl.innerHTML = lastEvents.map(e => {
+        const time = new Date(e.timestamp).toLocaleTimeString();
+        return `<div class="event-log-entry"><span class="event-time">${time}</span> <span class="event-type">${e.type}</span></div>`;
+      }).join('');
+      eventLogEl.scrollTop = eventLogEl.scrollHeight;
+    }
+  });
+
+  // Connection buttons
+  const connectBtn = document.getElementById('ws-connect-btn');
+  const disconnectBtn = document.getElementById('ws-disconnect-btn');
+  const apiUrlInput = document.getElementById('api-url-input');
+  const apiKeyInput = document.getElementById('api-key-input');
+
+  if (connectBtn) {
+    connectBtn.addEventListener('click', () => {
+      const url = apiUrlInput.value.trim();
+      const key = apiKeyInput.value.trim();
+      if (url) localStorage.setItem('jackbox-api-url', url);
+      if (key) localStorage.setItem('jackbox-api-key', key);
+      wsClient.connect(url, key);
+    });
+  }
+
+  if (disconnectBtn) {
+    disconnectBtn.addEventListener('click', () => {
+      wsClient.disconnect();
+      manager.transition('idle');
+    });
+  }
+
+  // Settings change handlers
+  apiUrlInput?.addEventListener('change', () => {
+    const url = apiUrlInput.value.trim();
+    if (url) localStorage.setItem('jackbox-api-url', url);
+  });
+  apiKeyInput?.addEventListener('change', () => {
+    localStorage.setItem('jackbox-api-key', apiKeyInput.value.trim());
+  });
+
+  // Volume slider
+  const volumeSlider = document.getElementById('volume-slider');
+  const volumeValue = document.getElementById('volume-value');
+  const themeSound = document.getElementById('theme-sound');
+  if (volumeSlider && volumeValue) {
+    volumeSlider.addEventListener('input', () => {
+      volumeValue.textContent = Math.round(volumeSlider.value * 100) + '%';
+      if (themeSound) themeSound.volume = volumeSlider.value;
+    });
+  }
+
+  // Test sound button
+  const testSoundBtn = document.getElementById('test-sound-btn');
+  const soundUrlInput = document.getElementById('sound-url-input');
+  if (testSoundBtn && themeSound && soundUrlInput) {
+    testSoundBtn.addEventListener('click', () => {
+      themeSound.src = soundUrlInput.value;
+      themeSound.volume = volumeSlider?.value || 0.5;
+      themeSound.currentTime = 0;
+      themeSound.loop = false;
+      themeSound.play().catch(err => {
+        console.log('[Test] Playback failed:', err.message);
+        alert('Audio playback failed. Check URL or browser autoplay permissions.');
+      });
+      setTimeout(() => {
+        themeSound.pause();
+        themeSound.loop = true;
+      }, 5000);
+    });
+  }
+
+  // Manual Update/Preview buttons
+  const updateBtn = document.getElementById('update-btn');
+  const previewBtn = document.getElementById('preview-btn');
+  if (updateBtn) {
+    updateBtn.addEventListener('click', () => {
+      // Manually trigger lobby state with current input values
+      const code1 = document.getElementById('code1-input')?.value || '';
+      const code2 = document.getElementById('code2-input')?.value || '';
+      const roomCode = code1 + code2;
+      if (roomCode) {
+        manager.handleEvent('game.added', {
+          session: {},
+          game: { room_code: roomCode, title: 'Manual', max_players: 8 },
+        });
+      }
+    });
+  }
+  if (previewBtn) {
+    previewBtn.addEventListener('click', () => {
+      const code1 = document.getElementById('code1-input')?.value || '';
+      const code2 = document.getElementById('code2-input')?.value || '';
+      const roomCode = code1 + code2;
+      if (roomCode) {
+        manager.handleEvent('game.added', {
+          session: {},
+          game: { room_code: roomCode, title: 'Preview', max_players: 8 },
+        });
+      }
+    });
+  }
+
+  // Toggle display button
+  const toggleDisplayBtn = document.getElementById('toggle-display-btn');
+  if (toggleDisplayBtn) {
+    toggleDisplayBtn.addEventListener('click', () => {
+      if (manager.state === 'lobby') {
+        manager.transition('idle');
+        toggleDisplayBtn.textContent = 'Show Display';
+      } else {
+        const code1 = document.getElementById('code1-input')?.value || '';
+        const code2 = document.getElementById('code2-input')?.value || '';
+        const roomCode = code1 + code2;
+        if (roomCode) {
+          manager.transition('lobby', { roomCode });
+          toggleDisplayBtn.textContent = 'Hide Display';
+        }
+      }
+    });
+  }
+
+  // Show/hide controls panel
+  const showControlsBtn = document.getElementById('show-controls-btn');
+  const controls = document.getElementById('controls');
+  if (showControlsBtn && controls) {
+    showControlsBtn.addEventListener('click', () => {
+      if (controls.style.display === 'block') {
+        controls.style.display = 'none';
+        showControlsBtn.textContent = 'Show Controls';
+      } else {
+        controls.style.display = 'block';
+        showControlsBtn.textContent = 'Hide Controls';
+      }
+    });
+  }
+
+  // Collapsible sections
+  document.querySelectorAll('.section-header').forEach(hdr => {
+    hdr.addEventListener('click', () => {
+      const content = hdr.nextElementSibling;
+      const indicator = hdr.querySelector('.toggle-indicator');
+      if (content.style.display === 'block') {
+        content.style.display = 'none';
+        indicator?.classList.remove('active');
+        hdr.classList.remove('active');
+      } else {
+        content.style.display = 'block';
+        indicator?.classList.add('active');
+        hdr.classList.add('active');
+      }
+    });
+  });
+
+  // Position toggle
+  const positionToggle = document.getElementById('position-toggle');
+  if (positionToggle && controls) {
+    positionToggle.addEventListener('change', () => {
+      controls.classList.toggle('bottom-position', positionToggle.checked);
+    });
+  }
+
+  // Inactivity timer
+  let inactivityTimer;
+  function resetInactivityTimer() {
+    clearTimeout(inactivityTimer);
+    inactivityTimer = setTimeout(() => {
+      if (controls) controls.style.display = 'none';
+      if (showControlsBtn) showControlsBtn.textContent = 'Show Controls';
+    }, 20000);
+  }
+  document.addEventListener('mousemove', resetInactivityTimer);
+  document.addEventListener('keypress', resetInactivityTimer);
+  document.addEventListener('click', resetInactivityTimer);
+  resetInactivityTimer();
+}
+
+export function initConnectionStatusHandler(wsClient) {
+  const wsStatusDot = document.getElementById('ws-status-dot');
+  const wsStatusText = document.getElementById('ws-status-text');
+  const wsConnectBtn = document.getElementById('ws-connect-btn');
+  const wsDisconnectRow = document.getElementById('ws-disconnect-row');
+  const apiUrlInput = document.getElementById('api-url-input');
+  const apiKeyInput = document.getElementById('api-key-input');
+
+  return (state, message) => {
+    if (wsStatusDot) wsStatusDot.className = 'status-dot ' + state;
+    if (wsStatusText) wsStatusText.textContent = message || state;
+
+    if (state === 'connected') {
+      if (wsConnectBtn) wsConnectBtn.style.display = 'none';
+      if (wsDisconnectRow) wsDisconnectRow.style.display = 'flex';
+      if (apiUrlInput) apiUrlInput.disabled = true;
+      if (apiKeyInput) apiKeyInput.disabled = true;
+    } else {
+      if (wsConnectBtn) wsConnectBtn.style.display = 'block';
+      if (wsDisconnectRow) wsDisconnectRow.style.display = 'none';
+      if (apiUrlInput) apiUrlInput.disabled = false;
+      if (apiKeyInput) apiKeyInput.disabled = false;
+    }
+  };
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add js/controls.js
+git commit -m "feat: add controls module with debug dashboard and override support"
+```
+
+---
+
+## Task 7: Update `optimized-controls.html` — Add Player List DOM, Dashboard DOM, CSS, Bootstrap
+
+**Files:**
+- Modify: `optimized-controls.html`
+
+This is the largest task. The HTML file needs:
+1. New CSS for player list and debug dashboard
+2. New DOM elements for player list container
+3. New DOM elements for debug dashboard section in controls
+4. New player list settings section in controls
+5. Replace the entire `<script>` block with a module bootstrap
+6. Remove the old inline JS (lines 634-1345)
+
+**Step 1: Add player list and dashboard CSS**
+
+Add new CSS rules after the existing `.mode-label` rule (around line 360, before `</style>`). These style the player list, the debug dashboard, and override controls.
+
+**Step 2: Add player list container to the DOM**
+
+After the `<div id="footer">` element, add a `<div id="player-list-container">` that will be positioned to the left or right of the room code.
+
+**Step 3: Add player list settings section to controls**
+
+After the Audio Settings section (around line 572), add a new collapsible "Player List Settings" section with:
+- Enable/disable checkbox (`#player-list-enabled`)
+- Position select: left/right (`#player-list-position`)
+- Font size input (`#player-list-font-size`)
+- Text color input (`#player-list-text-color`)
+- Empty slot color input (`#player-list-empty-color`)
+- Vertical offset input (`#player-list-offset`)
+
+**Step 4: Add Overlay Manager dashboard section to controls**
+
+After the Player List Settings section, add a new collapsible "Overlay Manager" section with:
+- State badge (`#manager-state`)
+- Room code display (`#manager-room-code`)
+- Session ID (`#manager-session-id`)
+- Game title (`#manager-game-title`)
+- Player count (`#manager-player-count`)
+- Component status table with override selects for `roomCode`, `audio`, `playerList`
+- Event log container (`#manager-event-log`)
+
+**Step 5: Replace inline script with module bootstrap**
+
+Replace the entire `<script>` block (lines 634-1345) with:
+
+```html
+<script type="module">
+  import { OverlayManager } from './js/state-manager.js';
+  import { WebSocketClient } from './js/websocket-client.js';
+  import { RoomCodeDisplay } from './js/room-code-display.js';
+  import { AudioController } from './js/audio-controller.js';
+  import { PlayerList } from './js/player-list.js';
+  import { initControls, initConnectionStatusHandler } from './js/controls.js';
+
+  const manager = new OverlayManager();
+
+  // Room Code Display component
+  const roomCodeDisplay = new RoomCodeDisplay();
+  roomCodeDisplay.init(
+    {
+      header: document.getElementById('header'),
+      footer: document.getElementById('footer'),
+      codePart1: document.getElementById('code-part1'),
+      codePart2: document.getElementById('code-part2'),
+    },
+    {
+      code1: document.getElementById('code1-input'),
+      code2: document.getElementById('code2-input'),
+      color1: document.getElementById('color1-input'),
+      color2: document.getElementById('color2-input'),
+      offset1: document.getElementById('offset1-input'),
+      offset2: document.getElementById('offset2-input'),
+      size: document.getElementById('size-input'),
+      cycle: document.getElementById('cycle-input'),
+      headerText: document.getElementById('header-text-input'),
+      headerColor: document.getElementById('header-color-input'),
+      headerSize: document.getElementById('header-size-input'),
+      headerOffset: document.getElementById('header-offset-input'),
+      footerText: document.getElementById('footer-text-input'),
+      footerColor: document.getElementById('footer-color-input'),
+      footerSize: document.getElementById('footer-size-input'),
+      footerOffset: document.getElementById('footer-offset-input'),
+      headerAppearDelay: document.getElementById('header-appear-delay'),
+      headerAppearDuration: document.getElementById('header-appear-duration'),
+      headerHideTime: document.getElementById('header-hide-time'),
+      headerHideDuration: document.getElementById('header-hide-duration'),
+      line1AppearDelay: document.getElementById('line1-appear-delay'),
+      line1AppearDuration: document.getElementById('line1-appear-duration'),
+      line1HideTime: document.getElementById('line1-hide-time'),
+      line1HideDuration: document.getElementById('line1-hide-duration'),
+      line2AppearDelay: document.getElementById('line2-appear-delay'),
+      line2AppearDuration: document.getElementById('line2-appear-duration'),
+      line2HideTime: document.getElementById('line2-hide-time'),
+      line2HideDuration: document.getElementById('line2-hide-duration'),
+    }
+  );
+  manager.registerComponent('roomCode', roomCodeDisplay);
+
+  // Audio Controller component
+  const audioController = new AudioController();
+  audioController.init(
+    document.getElementById('theme-sound'),
+    {
+      enabled: document.getElementById('sound-enabled'),
+      volume: document.getElementById('volume-slider'),
+      soundUrl: document.getElementById('sound-url-input'),
+    }
+  );
+  manager.registerComponent('audio', audioController);
+
+  // Player List component
+  const playerList = new PlayerList();
+  playerList.init(
+    document.getElementById('player-list-container'),
+    {
+      enabled: document.getElementById('player-list-enabled'),
+      position: document.getElementById('player-list-position'),
+      fontSize: document.getElementById('player-list-font-size'),
+      textColor: document.getElementById('player-list-text-color'),
+      emptyColor: document.getElementById('player-list-empty-color'),
+      offset: document.getElementById('player-list-offset'),
+    },
+    {
+      headerAppearDelay: document.getElementById('header-appear-delay'),
+      headerAppearDuration: document.getElementById('header-appear-duration'),
+    }
+  );
+  manager.registerComponent('playerList', playerList);
+
+  // WebSocket Client
+  const statusHandler = initConnectionStatusHandler();
+  const wsClient = new WebSocketClient({
+    onStatusChange: statusHandler,
+    onEvent: (type, data) => manager.handleEvent(type, data),
+    onSessionSubscribed: (sessionId) => {
+      console.log('[Bootstrap] Subscribed to session:', sessionId);
+    },
+  });
+
+  // Initialize controls, dashboard, and event bindings
+  initControls(manager, wsClient, {
+    roomCode: roomCodeDisplay,
+    audio: audioController,
+    playerList: playerList,
+  });
+
+  // Player list position reactivity
+  const plPositionSelect = document.getElementById('player-list-position');
+  const plContainer = document.getElementById('player-list-container');
+  if (plPositionSelect && plContainer) {
+    plPositionSelect.addEventListener('change', () => {
+      plContainer.classList.toggle('position-left', plPositionSelect.value === 'left');
+      plContainer.classList.toggle('position-right', plPositionSelect.value === 'right');
+    });
+    // Set initial position
+    plContainer.classList.add('position-' + (plPositionSelect.value || 'right'));
+  }
+
+  // Auto-connect from localStorage
+  const savedUrl = localStorage.getItem('jackbox-api-url');
+  const savedKey = localStorage.getItem('jackbox-api-key');
+  if (savedUrl) document.getElementById('api-url-input').value = savedUrl;
+  if (savedKey) document.getElementById('api-key-input').value = savedKey;
+  if (savedUrl && savedKey) {
+    setTimeout(() => wsClient.connect(savedUrl, savedKey), 500);
+  }
+
+  // Expose for debugging
+  window.__overlay = { manager, wsClient, roomCodeDisplay, audioController, playerList };
+</script>
+```
+
+**Step 6: Verify in browser**
+
+1. Open the HTML file in a browser
+2. Open DevTools console — should see no import errors
+3. Open controls panel — should see all existing settings plus new Player List and Overlay Manager sections
+4. Type a code in First/Second Line inputs, click Update — room code animation should play with audio
+5. Check `window.__overlay.manager.state` — should be `'lobby'`
+6. Click Hide Display — should transition to `'idle'` and stop everything
+
+**Step 7: Commit**
+
+```bash
+git add optimized-controls.html
+git commit -m "feat: integrate module system, add player list + dashboard DOM"
+```
+
+---
+
+## Task 8: End-to-End Verification & Polish
+
+**Files:**
+- Possibly modify: any of the above files for bug fixes
+
+**Step 1: Test the full WebSocket flow**
+
+If you have access to a running Game Picker API instance:
+1. Connect via the overlay's Connection Settings
+2. Verify `Connected` status
+3. Add a game with a room code in the Game Picker
+4. Verify: room code appears, audio plays, player list shows empty slots
+5. If shard monitor is running, verify players populate the list as they join
+6. When game starts: verify everything hides
+7. Add another game: verify full reset and clean restart
+
+If no API instance is available, test manually:
+1. Open DevTools console
+2. Run: `window.__overlay.manager.handleEvent('game.added', { session: { id: 1 }, game: { room_code: 'ABCD', title: 'Test Game', max_players: 6 } })`
+3. Verify: room code displays "AB" / "CD", audio plays, 6 empty player slots appear
+4. Run: `window.__overlay.manager.handleEvent('lobby.player-joined', { players: ['Alice'], playerCount: 1, maxPlayers: 6, playerName: 'Alice' })`
+5. Verify: first slot fills with "Alice"
+6. Run: `window.__overlay.manager.handleEvent('game.started', { playerCount: 1, players: ['Alice'] })`
+7. Verify: everything hides
+8. Run the `game.added` event again — verify audio restarts cleanly
+
+**Step 2: Test overrides**
+
+1. Set Room Code override to "Force Show"
+2. Verify it stays visible even when state transitions to `idle`
+3. Set Audio override to "Force Hide"
+4. Trigger a lobby — verify room code and player list appear but audio does not play
+5. Reset all overrides to "Auto"
+
+**Step 3: Test edge cases**
+
+- Rapid `game.added` events (new code while animation is running)
+- `room.disconnected` during lobby
+- `session.ended` during lobby
+- Player list with 0 maxPlayers (should default to 8)
+- Player list disabled in settings
+
+**Step 4: Fix any issues found**
+
+Address bugs discovered during testing.
+
+**Step 5: Final commit**
+
+```bash
+git add -A
+git commit -m "fix: address issues found during end-to-end testing"
+```
+
+---
+
+## Summary of Changes
+
+| File | Action | Purpose |
+|------|--------|---------|
+| `js/state-manager.js` | Create | OverlayManager state machine |
+| `js/websocket-client.js` | Create | Extracted WebSocket auth/connect/events |
+| `js/room-code-display.js` | Create | Extracted room code animation component |
+| `js/audio-controller.js` | Create | Extracted audio lifecycle (fixes restart bug) |
+| `js/player-list.js` | Create | New player slot list component |
+| `js/controls.js` | Create | Settings bindings + debug dashboard |
+| `optimized-controls.html` | Modify | Add player list/dashboard DOM + CSS, replace inline JS with module bootstrap |