docs: Update root README for v1.2.0 features

Adds a new toggleable feature that detects episode transitions via
mediaTitle mutation (loadeddata/MutationObserver), pauses the video,
and waits for all room peers to load the same episode before
executing a coordinated Force Sync play at 0:00.

Protocol:
- Add EPISODE_LOBBY and EPISODE_READY events to shared/constants.js
- Add EPISODE_LOBBY_TIMEOUT (60s) constant
- Relay both new events in server/index.js

Content Script (content.js):
- Layered detection: loadeddata + MutationObserver src-change + heartbeat
- Debounced onEpisodeTransition() sends signal ONLY; no eager pause
- PAUSE_FOR_LOBBY handler pauses only after background confirms feature enabled
- startLobbyPoll() polls title match without premature pause for non-initiators
- checkAndReportLobbyReady() pauses and sends EPISODE_READY_LOCAL on match
- CONTENT_BOOT recovery for re-injection after hard navigation

Background (background.js):
- Episode lobby state persisted in chrome.storage.session with recovery
- EPISODE_CHANGED: checks setting, creates lobby, sends PAUSE_FOR_LOBBY to tab
- EPISODE_LOBBY/READY server event handlers with dedup logic
- 60s timeout cancels lobby (Option B) with Chrome failure notification
- Peer departure handled: removes from readyPeers, re-checks completion
- executeEpisodeLobby() reuses existing Force Sync pipeline at targetTime 0.0
- Lobby cleared on LEAVE_ROOM; status exposed in GET_STATUS

Popup:
- Auto-Sync Next Episode toggle in Settings tab (default: off, opt-in)
- Episode Lobby status card in Sync tab with peer readiness display
- LOBBY_UPDATE message handler for real-time UI updates

Bumps APP_VERSION and manifest to 1.2.0

.github/workflows/release.yml

@@ -40,6 +40,7 @@ jobs:
           context: .
           file: server/Dockerfile
           push: true
+          platforms: linux/amd64,linux/arm64
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
 

.gitignore

@@ -38,7 +38,8 @@ coverage/
 # KoalaSync Specific
 # We ignore the synced files in the extension folder to ensure 
 # the root 'shared/' remains the Single Source of Truth.
-extension/shared/
+extension/shared/*
+!extension/shared/README.md
 
 # Temporary scratch files
 scratch/

README.md

@@ -2,6 +2,8 @@
 
 KoalaSync is a premium, lightweight Chrome Extension and Relay Server for synchronized video playback across any website (YouTube, Twitch, Netflix, and custom HTML5 players).
 
+**Latest Version**: `v1.2.0` (Episode Auto-Sync)
+
 > [!TIP]
 > **New Developers & AI Agents**: Please read [AI_INIT.md](AI_INIT.md) before starting work.
 
@@ -17,6 +19,7 @@ KoalaSync is a premium, lightweight Chrome Extension and Relay Server for synchr
 
 ## Key Features
 - **Global Synchronization**: Synchronize Play, Pause, and Seeking on any website with a `<video>` tag.
+- **Episode Auto-Sync**: Perfectly sync series binges. All peers wait until everyone has loaded the next episode before starting together (v1.2.0+).
 - **Smart Matching**: Automatically highlights and sorts tabs containing matching video titles.
 - **Noise Filtering**: Built-in domain blacklist to hide non-video sites from selection.
 - **Smart Identity**: Customizable usernames combined with unique hexadecimal peer IDs.
@@ -25,6 +28,7 @@ KoalaSync is a premium, lightweight Chrome Extension and Relay Server for synchr
 - **Integrated Diagnostics**: A dedicated "Dev" tab for real-time video state debugging.
 - **Seamless Invitations**: Smart invitation links that automatically configure the server and room credentials for your friends.
 
+
 ## Setup Instructions
 
 ### 1. Relay Server (Docker)

extension/background.js

@@ -1,4 +1,4 @@
-import { EVENTS, PROTOCOL_VERSION, OFFICIAL_SERVER_URL, OFFICIAL_SERVER_TOKEN, APP_VERSION } from './shared/constants.js';
+import { EVENTS, PROTOCOL_VERSION, OFFICIAL_SERVER_URL, OFFICIAL_SERVER_TOKEN, APP_VERSION, EPISODE_LOBBY_TIMEOUT } from './shared/constants.js';
 
 // --- State Management ---
 let socket = null;
@@ -8,7 +8,6 @@ let isConnecting = false;
 let peerId = null; // initialized via getPeerId()
 let currentRoom = null;
 let lastPeersJson = null;
-let heartbeatInterval = null;
 let currentTabId = null;
 let currentTabTitle = null; // New: for Smart Matching
 let logs = [];
@@ -30,8 +29,11 @@ function ensureState() {
             chrome.storage.session.get([
                 'logs', 'history', 'currentRoom', 'lastActionState', 
                 'eventQueue', 'isForceSyncInitiator', 'forceSyncAcks', 
-                'forceSyncDeadline', 'reconnectFailed', 'reconnectStartTime'
+                'forceSyncDeadline', 'reconnectFailed', 'reconnectStartTime', 'currentTabId', 'currentTabTitle',
+                'episodeLobby'
             ], (data) => {
+                if (data.currentTabId !== undefined) currentTabId = data.currentTabId;
+                if (data.currentTabTitle !== undefined) currentTabTitle = data.currentTabTitle;
                 // Merge data from storage with any early-arriving state
                 // New entries (added during boot) must stay at the top (index 0)
                 if (data.logs) logs = [...logs, ...data.logs].slice(0, 50);
@@ -65,6 +67,17 @@ function ensureState() {
                     }
                 }
 
+                // Recover Episode Lobby
+                if (data.episodeLobby && !episodeLobby) {
+                    episodeLobby = data.episodeLobby;
+                    const lobbyRemaining = (episodeLobby.createdAt + EPISODE_LOBBY_TIMEOUT) - Date.now();
+                    if (lobbyRemaining > 0) {
+                        episodeLobbyTimeout = setTimeout(() => cancelEpisodeLobby('Timeout'), lobbyRemaining);
+                    } else {
+                        cancelEpisodeLobby('Timeout (recovered)');
+                    }
+                }
+
                 storageInitialized = true;
                 
                 // Process any early logs/history that weren't captured in the spread
@@ -98,17 +111,30 @@ let isForceSyncInitiator = false;
 let forceSyncAcks = new Set();
 let forceSyncTimeout = null;
 
-// --- Storage Utils ---
-function startHeartbeat() {
-    // Session heartbeats are now handled by the chrome.alarms 'keepAlive' listener
-    // to ensure they survive Service Worker suspension in MV3.
-}
+// Episode Auto-Sync Lobby
+let episodeLobby = null; // { expectedTitle, initiatorPeerId, readyPeers: [], createdAt }
+let episodeLobbyTimeout = null;
 
-function stopHeartbeat() {
-    if (heartbeatInterval) {
-        clearInterval(heartbeatInterval);
-        heartbeatInterval = null;
-    }
+// --- Storage Utils ---
+
+/**
+ * Canonical peer data factory. All peer object construction must go through
+ * here to guarantee a consistent shape with predictable null defaults.
+ * @param {object} raw - Raw data from server event or heartbeat payload.
+ * @returns {object} Normalized peer data object.
+ */
+function createPeerData(raw) {
+    return {
+        peerId:        raw.peerId        || null,
+        username:      raw.username      || null,
+        tabTitle:      raw.tabTitle      || null,
+        mediaTitle:    raw.mediaTitle    || null,
+        playbackState: raw.playbackState || null,
+        currentTime:   raw.currentTime   != null ? raw.currentTime : null,
+        volume:        raw.volume        != null ? raw.volume       : null,
+        muted:         raw.muted         != null ? raw.muted        : null,
+        lastHeartbeat: Date.now()
+    };
 }
 
 async function getPeerId() {
@@ -121,13 +147,12 @@ async function getPeerId() {
 
 async function getSettings() {
     return new Promise(resolve => {
-        chrome.storage.sync.get(['serverUrl', 'useCustomServer', 'roomId', 'password', 'targetTabId', 'username'], (data) => {
+        chrome.storage.sync.get(['serverUrl', 'useCustomServer', 'roomId', 'password', 'username'], (data) => {
             resolve({
                 serverUrl: data.serverUrl || '',
                 useCustomServer: data.useCustomServer || false,
                 roomId: data.roomId || '',
                 password: data.password || '',
-                targetTabId: data.targetTabId || null,
                 username: data.username || ''
             });
         });
@@ -334,7 +359,7 @@ function updateBadgeStatus() {
     } else if (status === 'connecting') {
         chrome.action.setBadgeText({ text: '...' });
         chrome.action.setBadgeBackgroundColor({ color: '#fbbf24' });
-    } else if (status === 'connected' && currentTabId) {
+    } else if (status === 'connected' && currentRoom && currentTabId) {
         chrome.action.setBadgeText({ text: 'ON' });
         chrome.action.setBadgeBackgroundColor({ color: '#22c55e' });
     } else {
@@ -417,17 +442,13 @@ function addToHistory(action, senderId) {
 
 // --- Event Handlers ---
 function handleServerEvent(event, data) {
-    
     switch (event) {
         case EVENTS.ROOM_DATA:
             currentRoom = data;
             if (storageInitialized) chrome.storage.session.set({ currentRoom });
             addLog(`Joined Room: ${data.roomId}`, 'success');
             chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: data.peers }).catch(() => {});
-            
-            // Start background heartbeat
-            startHeartbeat();
-            
+                        
             // Inform Website Bridge & Popup
             const joinStatusMsg = { type: 'JOIN_STATUS', success: true, message: 'Joined' };
             chrome.runtime.sendMessage(joinStatusMsg).catch(() => {});
@@ -518,7 +539,7 @@ function handleServerEvent(event, data) {
                 if (!Array.isArray(currentRoom.peers)) currentRoom.peers = [];
                 if (data.status === 'joined') {
                     if (!currentRoom.peers.find(p => (p.peerId || p) === data.peerId)) {
-                        currentRoom.peers.push({ peerId: data.peerId, username: data.username, tabTitle: data.tabTitle });
+                        currentRoom.peers.push(createPeerData(data));
                         if (storageInitialized) chrome.storage.session.set({ currentRoom });
                         chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: currentRoom.peers }).catch(() => {});
                     }
@@ -526,6 +547,11 @@ function handleServerEvent(event, data) {
                     currentRoom.peers = currentRoom.peers.filter(p => (p.peerId || p) !== data.peerId);
                     if (storageInitialized) chrome.storage.session.set({ currentRoom });
                     chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: currentRoom.peers }).catch(() => {});
+
+                    // Episode Lobby: Handle peer departure
+                    if (episodeLobby) {
+                        checkEpisodeLobbyPeerDeparture();
+                    }
                 } else {
                     // Heartbeat/Update: Update tabTitle for matching
                     const peer = currentRoom.peers.find(p => (p.peerId || p) === data.peerId);
@@ -533,10 +559,16 @@ function handleServerEvent(event, data) {
                         if (typeof peer === 'object') {
                             peer.tabTitle = data.tabTitle;
                             peer.username = data.username;
+                            peer.mediaTitle = data.mediaTitle !== undefined ? data.mediaTitle : peer.mediaTitle;
+                            peer.playbackState = data.playbackState !== undefined ? data.playbackState : peer.playbackState;
+                            peer.currentTime = data.currentTime !== undefined ? data.currentTime : peer.currentTime;
+                            peer.volume = data.volume !== undefined ? data.volume : peer.volume;
+                            peer.muted = data.muted !== undefined ? data.muted : peer.muted;
+                            peer.lastHeartbeat = Date.now();
                         } else {
-                            // Migration: replace string with object
+                            // Migration: replace string peer with normalized object
                             const idx = currentRoom.peers.indexOf(peer);
-                            currentRoom.peers[idx] = { peerId: data.peerId, username: data.username, tabTitle: data.tabTitle };
+                            currentRoom.peers[idx] = createPeerData(data);
                         }
                         if (storageInitialized) chrome.storage.session.set({ currentRoom });
                         chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: currentRoom.peers }).catch(() => {});
@@ -544,6 +576,51 @@ function handleServerEvent(event, data) {
                 }
             }
             break;
+        case EVENTS.EPISODE_LOBBY:
+            if (data.senderId && data.expectedTitle) {
+                addLog(`Episode lobby from ${data.senderId}: "${data.expectedTitle}"`, 'info');
+                // If we already have a lobby for this same title, treat as dedup
+                if (episodeLobby && episodeLobby.expectedTitle === data.expectedTitle) {
+                    break; // Already tracking this lobby
+                }
+                // Cancel any existing lobby before starting a new one
+                if (episodeLobby) clearEpisodeLobbyState();
+                
+                episodeLobby = {
+                    expectedTitle: data.expectedTitle,
+                    initiatorPeerId: data.senderId,
+                    readyPeers: [],
+                    createdAt: Date.now()
+                };
+                persistEpisodeLobby();
+                broadcastLobbyUpdate();
+
+                // Start timeout
+                episodeLobbyTimeout = setTimeout(() => cancelEpisodeLobby('Timeout'), EPISODE_LOBBY_TIMEOUT);
+
+                // Forward to content script to start polling
+                if (currentTabId) {
+                    const tabId = parseInt(currentTabId);
+                    if (!isNaN(tabId)) {
+                        chrome.tabs.sendMessage(tabId, {
+                            type: 'EPISODE_LOBBY',
+                            expectedTitle: data.expectedTitle
+                        }).catch(() => {});
+                    }
+                }
+            }
+            break;
+        case EVENTS.EPISODE_READY:
+            if (episodeLobby && data.senderId) {
+                if (!episodeLobby.readyPeers.includes(data.senderId)) {
+                    episodeLobby.readyPeers.push(data.senderId);
+                    persistEpisodeLobby();
+                    broadcastLobbyUpdate();
+                    addLog(`Episode ready from ${data.senderId} (${episodeLobby.readyPeers.length})`, 'info');
+                    checkEpisodeLobbyCompletion();
+                }
+            }
+            break;
         default:
             addLog(`Received unknown event from server: ${event}`, 'warn');
             break;
@@ -564,6 +641,102 @@ function executeForceSync() {
     addLog('Force Sync Executed', 'success');
 }
 
+// --- Episode Auto-Sync Lobby Functions ---
+function persistEpisodeLobby() {
+    if (storageInitialized) chrome.storage.session.set({ episodeLobby });
+}
+
+function broadcastLobbyUpdate() {
+    chrome.runtime.sendMessage({ type: 'LOBBY_UPDATE', lobby: episodeLobby }).catch(() => {});
+}
+
+function clearEpisodeLobbyState() {
+    if (episodeLobbyTimeout) clearTimeout(episodeLobbyTimeout);
+    episodeLobbyTimeout = null;
+    episodeLobby = null;
+    if (storageInitialized) chrome.storage.session.set({ episodeLobby: null });
+    broadcastLobbyUpdate();
+
+    // Notify content script to stop polling
+    if (currentTabId) {
+        const tabId = parseInt(currentTabId);
+        if (!isNaN(tabId)) {
+            chrome.tabs.sendMessage(tabId, { type: 'EPISODE_LOBBY_CANCEL' }).catch(() => {});
+        }
+    }
+}
+
+function cancelEpisodeLobby(reason) {
+    if (!episodeLobby) return;
+    const title = episodeLobby.expectedTitle;
+    clearEpisodeLobbyState();
+    addLog(`Episode lobby cancelled: ${reason} for "${title}"`, 'warn');
+
+    // Chrome notification on failure (per Q2: only notify on failure)
+    chrome.notifications.create(`episode_${Date.now()}`, {
+        type: 'basic',
+        iconUrl: 'icons/icon128.png',
+        title: 'KoalaSync — Episode Sync Failed',
+        message: `Auto-sync cancelled: ${reason}. You may need to manually sync.`,
+        priority: 1
+    });
+}
+
+function executeEpisodeLobby() {
+    if (!episodeLobby) return;
+    const title = episodeLobby.expectedTitle;
+    clearEpisodeLobbyState();
+    addLog(`Episode lobby complete: Starting "${title}" via Force Sync`, 'success');
+
+    // Trigger a standard Force Sync at targetTime 0.0
+    isForceSyncInitiator = true;
+    forceSyncAcks.clear();
+    const deadline = Date.now() + 5000;
+    chrome.storage.session.set({ 
+        isForceSyncInitiator: true, 
+        forceSyncAcks: [], 
+        forceSyncDeadline: deadline 
+    });
+
+    const syncPayload = { targetTime: 0.0 };
+    emit(EVENTS.FORCE_SYNC_PREPARE, { ...syncPayload, peerId });
+    routeToContent(EVENTS.FORCE_SYNC_PREPARE, syncPayload);
+
+    forceSyncTimeout = setTimeout(() => {
+        if (isForceSyncInitiator) {
+            addLog('Force Sync (Episode): Timeout waiting for ACKs, executing anyway...', 'warn');
+            executeForceSync();
+        }
+    }, 5000);
+}
+
+function checkEpisodeLobbyCompletion() {
+    if (!episodeLobby || !currentRoom) return;
+    const peerCount = currentRoom.peers ? currentRoom.peers.length : 1;
+    if (episodeLobby.readyPeers.length >= peerCount) {
+        executeEpisodeLobby();
+    }
+}
+
+function checkEpisodeLobbyPeerDeparture() {
+    if (!episodeLobby || !currentRoom) return;
+    const remainingPeerIds = currentRoom.peers.map(p => typeof p === 'object' ? p.peerId : p);
+    
+    // If only we remain, cancel the lobby
+    if (remainingPeerIds.length <= 1) {
+        cancelEpisodeLobby('All other peers left');
+        return;
+    }
+
+    // Filter readyPeers to only include peers still in the room
+    episodeLobby.readyPeers = episodeLobby.readyPeers.filter(id => remainingPeerIds.includes(id));
+    persistEpisodeLobby();
+    broadcastLobbyUpdate();
+
+    // Re-check if all remaining peers are now ready
+    checkEpisodeLobbyCompletion();
+}
+
 function updateLastAction(action, senderId, timestamp = Date.now()) {
     lastActionState = {
         action,
@@ -576,10 +749,6 @@ function updateLastAction(action, senderId, timestamp = Date.now()) {
 }
 
 async function routeToContent(action, payload) {
-    if (!currentTabId) {
-        const settings = await getSettings();
-        currentTabId = settings.targetTabId;
-    }
     if (!currentTabId) return;
 
     const tabId = parseInt(currentTabId);
@@ -633,23 +802,7 @@ chrome.alarms.onAlarm.addListener(async (alarm) => {
     }
 });
 
-setInterval(async () => {
-    await ensureState();
-    // Calling a chrome API keeps the SW alive in MV3 (Chrome 110+)
-    chrome.storage.session.get('keepAlive', () => {});
-    if (!socket || socket.readyState !== WebSocket.OPEN) {
-        connect();
-    } else if (currentRoom) {
-        // Redundant heartbeat for active SW state
-        const settings = await getSettings();
-        emit(EVENTS.PEER_STATUS, { 
-            peerId, 
-            status: 'heartbeat',
-            username: settings.username,
-            tabTitle: currentTabTitle 
-        });
-    }
-}, 30000); // every 30s
+
 
 // --- Extension Message Listeners ---
 chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
@@ -679,11 +832,13 @@ async function handleAsyncMessage(message, sender, sendResponse) {
         } else {
             connect();
         }
+        sendResponse({ status: 'ok' });
     } else if (message.type === 'RETRY_CONNECT') {
         reconnectFailed = false;
         reconnectStartTime = null;
         reconnectDelay = 1000;
         connect();
+        sendResponse({ status: 'ok' });
     } else if (message.type === 'GET_STATUS') {
         const isConnected = socket && socket.readyState === WebSocket.OPEN && isNamespaceJoined;
         let status = isConnected ? 'connected' : (isConnecting || (socket && socket.readyState === WebSocket.CONNECTING) ? 'connecting' : 'disconnected');
@@ -693,27 +848,33 @@ async function handleAsyncMessage(message, sender, sendResponse) {
             peerId, 
             peers: currentRoom ? currentRoom.peers : [],
             lastActionState,
-            targetTabId: currentTabId
+            targetTabId: currentTabId,
+            episodeLobby: episodeLobby
         });
     } else if (message.type === 'LEAVE_ROOM') {
         emit(EVENTS.LEAVE_ROOM, { peerId });
         currentRoom = null;
         currentTabId = null;
-        stopHeartbeat();
+
         updateBadgeStatus();
         
         isForceSyncInitiator = false;
         forceSyncAcks.clear();
         if (forceSyncTimeout) clearTimeout(forceSyncTimeout);
 
+        // Cancel any active episode lobby
+        clearEpisodeLobbyState();
+
         chrome.storage.session.set({ 
             currentRoom: null,
             isForceSyncInitiator: false,
             forceSyncAcks: [],
-            forceSyncDeadline: null
+            forceSyncDeadline: null,
+            episodeLobby: null
         });
         addLog('Left Room', 'info');
         chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: [] }).catch(() => {});
+        sendResponse({ status: 'ok' });
     } else if (message.type === 'CLEAR_LOGS') {
         logs = [];
         sendResponse({ status: 'ok' });
@@ -725,6 +886,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {
         if (socket && socket.readyState === WebSocket.OPEN) {
             socket.send(`42${JSON.stringify([EVENTS.GET_ROOMS])}`);
         }
+        sendResponse({ status: 'ok' });
     } else if (message.type === 'WEB_JOIN_REQUEST') {
         const { roomId, password, useCustomServer, serverUrl } = message;
         chrome.storage.sync.set({ 
@@ -751,7 +913,6 @@ async function handleAsyncMessage(message, sender, sendResponse) {
             }
             sendResponse({ status: 'ok' });
         });
-        return true; // Keep channel open for async getSettings
     } else if (message.type === 'REGENERATE_ID') {
         const newId = self.crypto.randomUUID().substring(0, 8);
         chrome.storage.local.set({ peerId: newId }, () => {
@@ -760,7 +921,6 @@ async function handleAsyncMessage(message, sender, sendResponse) {
             if (socket) socket.close(); // Force reconnect with new ID
             sendResponse({ peerId: newId });
         });
-        return true;
     } else if (message.type === 'GET_VIDEO_STATE') {
         const { tabId } = message;
         if (!tabId) {
@@ -774,47 +934,53 @@ async function handleAsyncMessage(message, sender, sendResponse) {
                 sendResponse(res);
             }
         });
-        return true; // Keep channel open
     } else if (message.type === 'CONTENT_EVENT') {
-        if (sender.tab) {
-            currentTabId = sender.tab.id;
-            currentTabTitle = sender.tab.title ? sender.tab.title.substring(0, 50) : null;
-            updateBadgeStatus();
-        } else {
-            // Event coming from POPUP: We must also route it to our OWN content script
-            routeToContent(message.action, message.payload);
-        }
-        
-        // Update local state as initiator
-        const timestamp = Date.now();
-        updateLastAction(message.action, 'You', timestamp);
-        message.payload.actionTimestamp = timestamp;
-        
-        // Events coming from content script or popup
-        if (message.action === EVENTS.FORCE_SYNC_PREPARE) {
-            isForceSyncInitiator = true;
-            forceSyncAcks.clear();
-            const deadline = Date.now() + 5000;
-            chrome.storage.session.set({ 
-                isForceSyncInitiator: true, 
-                forceSyncAcks: [], 
-                forceSyncDeadline: deadline 
-            });
-            addLog('Initiating Force Sync...', 'info');
+        const processEvent = () => {
+            const timestamp = Date.now();
+            updateLastAction(message.action, 'You', timestamp);
+            message.payload.actionTimestamp = timestamp;
             
-            // Route to our own content script so we pause and seek
-            routeToContent(EVENTS.FORCE_SYNC_PREPARE, message.payload);
- 
-            // Timeout if not everyone ACKs
-            forceSyncTimeout = setTimeout(() => {
-                if (isForceSyncInitiator) {
-                    addLog('Force Sync: Timeout waiting for ACKs, executing anyway...', 'warn');
-                    executeForceSync();
-                }
-            }, 5000);
+            if (message.action === EVENTS.FORCE_SYNC_PREPARE) {
+                isForceSyncInitiator = true;
+                forceSyncAcks.clear();
+                const deadline = Date.now() + 5000;
+                chrome.storage.session.set({ 
+                    isForceSyncInitiator: true, 
+                    forceSyncAcks: [], 
+                    forceSyncDeadline: deadline 
+                });
+                addLog('Initiating Force Sync...', 'info');
+                
+                routeToContent(EVENTS.FORCE_SYNC_PREPARE, message.payload);
+     
+                forceSyncTimeout = setTimeout(() => {
+                    if (isForceSyncInitiator) {
+                        addLog('Force Sync: Timeout waiting for ACKs, executing anyway...', 'warn');
+                        executeForceSync();
+                    }
+                }, 5000);
+            }
+            addToHistory(message.action, 'You');
+            emit(message.action, { ...message.payload, peerId });
+            sendResponse({ status: 'ok' });
+        };
+
+        if (sender.tab) {
+            const senderTabId = sender.tab.id;
+            
+            if (!currentTabId || currentTabId !== senderTabId) {
+                sendResponse({ status: 'ignored_unselected_tab' });
+                return;
+            }
+            
+            currentTabTitle = sender.tab.title ? sender.tab.title.substring(0, 50) : null;
+            chrome.storage.session.set({ currentTabTitle });
+            updateBadgeStatus();
+            processEvent();
+        } else {
+            routeToContent(message.action, message.payload);
+            processEvent();
         }
-        addToHistory(message.action, 'You');
-        emit(message.action, { ...message.payload, peerId });
     } else if (message.type === 'FORCE_SYNC_ACK') {
         if (isForceSyncInitiator) {
             forceSyncAcks.add(peerId);
@@ -827,6 +993,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {
         } else {
             emit(EVENTS.FORCE_SYNC_ACK, { peerId });
         }
+        sendResponse({ status: 'ok' });
     } else if (message.type === 'CMD_ACK') {
         // Content script successfully ran a command. Send ACK back to the initiator.
         if (currentCommandSenderId && currentCommandSenderId !== peerId) {
@@ -836,17 +1003,153 @@ async function handleAsyncMessage(message, sender, sendResponse) {
                 actionTimestamp: message.actionTimestamp 
             });
         }
+        sendResponse({ status: 'ok' });
     } else if (message.type === 'HEARTBEAT') {
         if (sender.tab) {
-            currentTabId = sender.tab.id;
+            const senderTabId = sender.tab.id;
+            
+            if (!currentTabId || currentTabId !== senderTabId) {
+                sendResponse({ status: 'ignored_unselected_tab' });
+                return;
+            }
+            
             currentTabTitle = sender.tab.title ? sender.tab.title.substring(0, 50) : null;
+            chrome.storage.session.set({ currentTabTitle });
+            updateBadgeStatus();
         }
-        // Peer status heartbeat from content script
+
         getSettings().then(settings => {
-            emit(EVENTS.PEER_STATUS, { ...message.payload, peerId, username: settings.username, tabTitle: currentTabTitle });
+            const statusPayload = { ...message.payload, peerId, username: settings.username, tabTitle: currentTabTitle };
+            emit(EVENTS.PEER_STATUS, statusPayload);
+
+            if (currentRoom && currentRoom.peers) {
+                const me = currentRoom.peers.find(p => (p.peerId || p) === peerId);
+                if (me && typeof me === 'object') {
+                    me.tabTitle = currentTabTitle;
+                    me.username = settings.username;
+                    me.mediaTitle = message.payload.mediaTitle;
+                    me.playbackState = message.payload.playbackState;
+                    me.currentTime = message.payload.currentTime;
+                    me.volume = message.payload.volume;
+                    me.muted = message.payload.muted;
+                    me.lastHeartbeat = Date.now();
+                    chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: currentRoom.peers }).catch(() => {});
+                }
+            }
+            sendResponse({ status: 'ok' });
         });
+    } else if (message.type === 'SET_TARGET_TAB') {
+        currentTabId = message.tabId;
+        currentTabTitle = message.tabTitle;
+        chrome.storage.session.set({ currentTabId, currentTabTitle });
+        updateBadgeStatus();
+        
+        if (currentTabId) {
+            chrome.scripting.executeScript({
+                target: { tabId: currentTabId },
+                files: ['content.js']
+            }).catch(err => {
+                addLog(`Failed to inject into tab: ${err.message}`, 'warn');
+            });
+        }
+        
+        sendResponse({ status: 'ok' });
     } else if (message.type === 'LOG') {
         addLog(`[Content] ${message.message}`, message.level || 'info');
+        sendResponse({ status: 'ok' });
+    } else if (message.type === 'EPISODE_CHANGED') {
+        // Content script detected an episode transition
+        if (sender.tab) {
+            const senderTabId = sender.tab.id;
+            if (!currentTabId || currentTabId !== senderTabId) {
+                sendResponse({ status: 'ignored_unselected_tab' });
+                return;
+            }
+        }
+
+        const newTitle = message.payload && message.payload.newTitle;
+        if (!newTitle) {
+            sendResponse({ status: 'no_title' });
+            return;
+        }
+
+        // Check setting
+        const epSettings = await chrome.storage.sync.get(['autoSyncNextEpisode']);
+        if (!epSettings.autoSyncNextEpisode) {
+            addLog(`Episode change detected ("${newTitle}") but Auto-Sync is disabled.`, 'info');
+            sendResponse({ status: 'disabled' });
+            return;
+        }
+
+        // If lobby already exists for this title, just mark self ready
+        if (episodeLobby && episodeLobby.expectedTitle === newTitle) {
+            if (!episodeLobby.readyPeers.includes(peerId)) {
+                episodeLobby.readyPeers.push(peerId);
+                persistEpisodeLobby();
+                broadcastLobbyUpdate();
+                emit(EVENTS.EPISODE_READY, { peerId, title: newTitle });
+                checkEpisodeLobbyCompletion();
+            }
+            sendResponse({ status: 'ready_sent' });
+            return;
+        }
+
+        // Cancel any existing lobby for a different episode
+        if (episodeLobby) clearEpisodeLobbyState();
+
+        // Create new lobby
+        episodeLobby = {
+            expectedTitle: newTitle,
+            initiatorPeerId: peerId,
+            readyPeers: [peerId], // We are already ready
+            createdAt: Date.now()
+        };
+        persistEpisodeLobby();
+        broadcastLobbyUpdate();
+        addLog(`Episode lobby created: "${newTitle}"`, 'info');
+
+        // Tell content script to pause the video and start polling
+        // (This is the only place we pause — after confirming the feature is enabled)
+        if (sender.tab && sender.tab.id) {
+            chrome.tabs.sendMessage(sender.tab.id, {
+                type: 'PAUSE_FOR_LOBBY',
+                expectedTitle: newTitle
+            }).catch(() => {});
+        }
+
+        // Broadcast to room
+        emit(EVENTS.EPISODE_LOBBY, { peerId, expectedTitle: newTitle });
+
+        // Start timeout (Q1: Option B — cancel on timeout)
+        episodeLobbyTimeout = setTimeout(() => cancelEpisodeLobby('Timeout — not all peers loaded the episode'), EPISODE_LOBBY_TIMEOUT);
+
+        // Immediate check — maybe we're the only one in the room
+        checkEpisodeLobbyCompletion();
+
+        sendResponse({ status: 'lobby_created' });
+    } else if (message.type === 'EPISODE_READY_LOCAL') {
+        // Content script confirmed it loaded the lobby episode
+        if (episodeLobby && message.payload && message.payload.title === episodeLobby.expectedTitle) {
+            if (!episodeLobby.readyPeers.includes(peerId)) {
+                episodeLobby.readyPeers.push(peerId);
+                persistEpisodeLobby();
+                broadcastLobbyUpdate();
+                emit(EVENTS.EPISODE_READY, { peerId, title: message.payload.title });
+                addLog(`Local episode ready: "${message.payload.title}"`, 'success');
+                checkEpisodeLobbyCompletion();
+            }
+        }
+        sendResponse({ status: 'ok' });
+    } else if (message.type === 'CONTENT_BOOT') {
+        // Content script re-injected, check if there's an active lobby
+        if (episodeLobby) {
+            sendResponse({ lobbyActive: true, expectedTitle: episodeLobby.expectedTitle });
+        } else {
+            sendResponse({ lobbyActive: false });
+        }
+    } else {
+        // Final fallback to prevent channel hanging
+        sendResponse({ error: 'unhandled_message' });
     }
 }
 
@@ -855,11 +1158,21 @@ chrome.tabs.onRemoved.addListener((tabId) => {
     if (tabId === currentTabId) {
         currentTabId = null;
         currentTabTitle = null;
-        chrome.storage.sync.set({ targetTabId: null });
+        chrome.storage.session.set({ currentTabId: null, currentTabTitle: null });
         updateBadgeStatus();
         addLog('Target tab closed.', 'warn');
     }
 });
 
+// Re-inject on full page refresh
+chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
+    if (currentTabId && tabId === parseInt(currentTabId) && changeInfo.status === 'complete') {
+        chrome.scripting.executeScript({
+            target: { tabId },
+            files: ['content.js']
+        }).catch(() => {});
+    }
+});
+
 // Initial Connect
 connect();

extension/content.js

@@ -22,22 +22,27 @@
         FORCE_SYNC_PREPARE: "force_sync_prepare",
         FORCE_SYNC_ACK: "force_sync_ack",
         FORCE_SYNC_EXECUTE: "force_sync_execute",
-        PEER_STATUS: "peer_status"
+        PEER_STATUS: "peer_status",
+        EPISODE_LOBBY: "episode_lobby",
+        EPISODE_READY: "episode_ready"
     };
 
-    let lastTargetState = null;
-    let targetStateTimeout = null;
+    let expectedEvents = new Set();
+    let expectedTimeouts = {};
 
-    function setTargetState(state) {
-        lastTargetState = state;
-        if (targetStateTimeout) clearTimeout(targetStateTimeout);
-        if (state !== null) {
-            // Seek events might take longer than play/pause, using 2s for safety
-            const timeout = state === 'seek' ? 2000 : 1500;
-            targetStateTimeout = setTimeout(() => {
-                lastTargetState = null;
-            }, timeout);
-        }
+    // --- Episode Auto-Sync State ---
+    let lastKnownMediaTitle = null;
+    let episodeTransitionDebounce = null;
+    let pendingLobbyTitle = null; // Title we're waiting to match (from remote lobby)
+    let lobbyPollTimer = null;
+
+    function expectEvent(state) {
+        expectedEvents.add(state);
+        if (expectedTimeouts[state]) clearTimeout(expectedTimeouts[state]);
+        const timeout = state === 'seek' ? 10000 : 1500;
+        expectedTimeouts[state] = setTimeout(() => {
+            expectedEvents.delete(state);
+        }, timeout);
     }
 
     function reportLog(message, level = 'info') {
@@ -50,6 +55,100 @@
         return videos.length > 0 ? videos[0] : null;
     }
 
+    // --- Episode Auto-Sync: Detection ---
+    function getMediaTitle() {
+        return (navigator.mediaSession && navigator.mediaSession.metadata)
+            ? navigator.mediaSession.metadata.title
+            : null;
+    }
+
+    function checkEpisodeTransition() {
+        const currentTitle = getMediaTitle();
+        const video = findVideo();
+
+        // Only trigger if: we had a previous title, the title changed,
+        // a video exists, and we're near the start of new content.
+        if (lastKnownMediaTitle && currentTitle
+            && currentTitle !== lastKnownMediaTitle
+            && video
+            && video.currentTime < 5
+            && video.readyState >= 1) {
+            onEpisodeTransition(currentTitle);
+        }
+
+        // Always track the latest known title
+        if (currentTitle) lastKnownMediaTitle = currentTitle;
+    }
+
+    function onEpisodeTransition(newTitle) {
+        // Debounce: prevent duplicate fires from multiple signals
+        if (episodeTransitionDebounce) return;
+        episodeTransitionDebounce = setTimeout(() => {
+            episodeTransitionDebounce = null;
+        }, 2000);
+
+        reportLog(`Episode transition detected: "${newTitle}"`, 'info');
+
+        // Do NOT pause here. We notify background.js first.
+        // Background checks the setting; if enabled it creates a lobby
+        // and sends back PAUSE_FOR_LOBBY so we only freeze if the feature is on.
+        chrome.runtime.sendMessage({
+            type: 'EPISODE_CHANGED',
+            payload: { newTitle }
+        }).catch(() => {});
+    }
+
+    function checkAndReportLobbyReady(expectedTitle) {
+        const video = findVideo();
+        const currentTitle = getMediaTitle();
+
+        if (video && currentTitle && currentTitle === expectedTitle
+            && video.currentTime < 5 && video.readyState >= 1) {
+            // Match! Pause at start and report ready.
+            if (!video.paused) {
+                expectEvent('paused');
+                video.pause();
+            }
+            stopLobbyPoll();
+            chrome.runtime.sendMessage({
+                type: 'EPISODE_READY_LOCAL',
+                payload: { title: currentTitle }
+            }).catch(() => {});
+            reportLog(`Episode lobby: Ready for "${currentTitle}"`, 'success');
+            return true;
+        }
+        return false;
+    }
+
+    function startLobbyPoll(expectedTitle) {
+        stopLobbyPoll();
+        pendingLobbyTitle = expectedTitle;
+
+        // NOTE: Do NOT pause here. Three callers reach this function:
+        // 1. PAUSE_FOR_LOBBY (initiator): already paused by that handler before calling us.
+        // 2. EPISODE_LOBBY (non-initiator): peer may still be on the PREVIOUS episode — pausing
+        //    would freeze them mid-episode. The pause happens inside checkAndReportLobbyReady()
+        //    only once their title actually matches.
+        // 3. CONTENT_BOOT recovery: same reasoning as (2).
+
+        // Check immediately
+        if (checkAndReportLobbyReady(expectedTitle)) return;
+
+        // Poll every 2 seconds — no log spam, internal only
+        lobbyPollTimer = setInterval(() => {
+            checkAndReportLobbyReady(expectedTitle);
+        }, 2000);
+    }
+
+
+    function stopLobbyPoll() {
+        pendingLobbyTitle = null;
+        if (lobbyPollTimer) {
+            clearInterval(lobbyPollTimer);
+            lobbyPollTimer = null;
+        }
+    }
+
     // --- Helper: YouTube/Twitch specific actions ---
     function tryMediaAction(action, data) {
         const video = findVideo();
@@ -74,11 +173,11 @@
                 if (ytButton) {
                     const isCurrentlyPlaying = !video.paused;
                     if ((action === EVENTS.PLAY && !isCurrentlyPlaying) || (action === EVENTS.PAUSE && isCurrentlyPlaying)) {
-                        setTargetState(action === EVENTS.PLAY ? 'playing' : 'paused');
+                        expectEvent(action === EVENTS.PLAY ? 'playing' : 'paused');
                         ytButton.click();
                     }
                     if (action === EVENTS.SEEK) {
-                        setTargetState('seek');
+                        expectEvent('seek');
                         video.currentTime = data.targetTime;
                     }
                     return;
@@ -90,11 +189,11 @@
                 if (twitchButton) {
                     const isCurrentlyPlaying = !video.paused;
                     if ((action === EVENTS.PLAY && !isCurrentlyPlaying) || (action === EVENTS.PAUSE && isCurrentlyPlaying)) {
-                        setTargetState(action === EVENTS.PLAY ? 'playing' : 'paused');
+                        expectEvent(action === EVENTS.PLAY ? 'playing' : 'paused');
                         twitchButton.click();
                     }
                     if (action === EVENTS.SEEK) {
-                        setTargetState('seek');
+                        expectEvent('seek');
                         video.currentTime = data.targetTime;
                     }
                     return;
@@ -103,16 +202,16 @@
 
             // Fallback for native HTML5
             if (action === EVENTS.PLAY) {
-                setTargetState('playing');
+                expectEvent('playing');
                 video.play().catch((e) => {
                     reportLog(`Playback prevented: ${e.message}`, 'warn');
-                    setTargetState(null);
+                    expectedEvents.delete('playing');
                 });
             } else if (action === EVENTS.PAUSE) {
-                setTargetState('paused');
+                expectEvent('paused');
                 video.pause();
             } else if (action === EVENTS.SEEK) {
-                setTargetState('seek');
+                expectEvent('seek');
                 video.currentTime = data.targetTime;
             }
         } catch (e) {
@@ -135,7 +234,7 @@
 
                 elapsed += interval;
                 const timeDiff = Math.abs(video.currentTime - targetTime);
-                const ready = video.readyState >= 3 && timeDiff < 1.0;
+                const ready = video.readyState >= 3 && timeDiff < 2.0;
                 if (ready) {
                     clearInterval(timer);
                     resolve(true);
@@ -175,7 +274,8 @@
                         reportLog(`Media Action Error: Invalid force sync payload - ${JSON.stringify(payload)}`, 'error');
                         return;
                     }
-                    setTargetState('paused');
+                    expectEvent('paused');
+                    expectEvent('seek');
                     video.pause();
                     video.currentTime = payload.targetTime;
                     pollSeekReady(payload.targetTime).then((ready) => {
@@ -183,23 +283,79 @@
                     });
                 }
             } else if (action === EVENTS.FORCE_SYNC_EXECUTE) {
+                stopLobbyPoll(); // Clear any pending lobby on force sync
                 tryMediaAction(EVENTS.PLAY);
                 chrome.runtime.sendMessage({ type: 'CMD_ACK', actionTimestamp: message.actionTimestamp });
             }
         }
 
+        // Episode Auto-Sync: Lobby notification from background
+        if (message.type === 'EPISODE_LOBBY') {
+            const expectedTitle = message.expectedTitle;
+            if (expectedTitle) {
+                reportLog(`Episode lobby received: waiting for "${expectedTitle}"`, 'info');
+                startLobbyPoll(expectedTitle);
+            }
+            sendResponse({ status: 'ok' });
+            return true;
+        }
+
+        // Episode Auto-Sync: Lobby cancelled by background
+        if (message.type === 'EPISODE_LOBBY_CANCEL') {
+            stopLobbyPoll();
+            sendResponse({ status: 'ok' });
+            return true;
+        }
+
+        // Episode Auto-Sync: Background confirmed lobby created, pause the video
+        if (message.type === 'PAUSE_FOR_LOBBY') {
+            const video = findVideo();
+            if (video && !video.paused) {
+                expectEvent('paused');
+                video.pause();
+            }
+            // Start lobby poll now that we know the feature is enabled
+            if (message.expectedTitle) {
+                startLobbyPoll(message.expectedTitle);
+            }
+            sendResponse({ status: 'ok' });
+            return true;
+        }
+
         if (message.type === 'GET_VIDEO_STATE') {
             const video = findVideo();
             if (video) {
+                const dataAttributes = {};
+                if (video.attributes) {
+                    for (const attr of video.attributes) {
+                        if (attr.name.startsWith('data-')) {
+                            dataAttributes[attr.name] = attr.value;
+                        }
+                    }
+                }
+
+                const metadata = (navigator.mediaSession && navigator.mediaSession.metadata) ? {
+                    title: navigator.mediaSession.metadata.title,
+                    artist: navigator.mediaSession.metadata.artist,
+                    album: navigator.mediaSession.metadata.album,
+                    artwork: Array.from(navigator.mediaSession.metadata.artwork || []).map(a => a.src)
+                } : null;
+
                 sendResponse({
                     paused: video.paused,
                     currentTime: video.currentTime,
                     duration: video.duration || 0,
                     readyState: video.readyState,
                     muted: video.muted,
+                    volume: video.volume,
                     playbackRate: video.playbackRate,
                     url: window.location.href,
-                    id: video.id || 'none'
+                    id: video.id || 'none',
+                    className: video.className || 'none',
+                    src: video.src || 'none',
+                    currentSrc: video.currentSrc || 'none',
+                    dataAttributes,
+                    metadata
                 });
             } else {
                 sendResponse({ error: 'No video found' });
@@ -215,10 +371,12 @@
         const current = video.currentTime;
         if (!Number.isFinite(current)) return;
 
+        const mediaTitle = (navigator.mediaSession && navigator.mediaSession.metadata) ? navigator.mediaSession.metadata.title : null;
+
         const eventState = action === EVENTS.PLAY ? 'playing' : (action === EVENTS.PAUSE ? 'paused' : (action === EVENTS.SEEK ? 'seek' : null));
         
-        if (eventState && lastTargetState === eventState) {
-            setTargetState(null); // Consume the match
+        if (eventState && expectedEvents.has(eventState)) {
+            expectedEvents.delete(eventState); // Consume the match
             return; // Ignore event caused by our programmatic action
         }
         
@@ -228,6 +386,7 @@
             payload: {
                 currentTime: current,
                 targetTime: current,
+                mediaTitle: mediaTitle,
                 timestamp: Date.now()
             }
         });
@@ -239,18 +398,30 @@
 
     let lastVideoSrc = null;
 
+    // Episode detection handler for loadeddata event
+    const handleLoadedData = () => {
+        checkEpisodeTransition();
+    };
+
     function setupListeners() {
         const video = findVideo();
         if (video) {
             video.removeEventListener('play', handlePlay);
             video.removeEventListener('pause', handlePause);
             video.removeEventListener('seeked', handleSeeked);
+            video.removeEventListener('loadeddata', handleLoadedData);
 
             video.addEventListener('play', handlePlay);
             video.addEventListener('pause', handlePause);
             video.addEventListener('seeked', handleSeeked);
+            video.addEventListener('loadeddata', handleLoadedData);
             video.dataset.koalaAttached = 'true';
             lastVideoSrc = video.currentSrc || video.src;
+
+            // Initialize episode tracking title on first attach
+            if (!lastKnownMediaTitle) {
+                lastKnownMediaTitle = getMediaTitle();
+            }
         }
     }
 
@@ -266,6 +437,10 @@
         const currentSrc = video.currentSrc || video.src;
 
         if (!video.dataset.koalaAttached || (lastVideoSrc && currentSrc && lastVideoSrc !== currentSrc)) {
+            // If src changed, also check for episode transition
+            if (lastVideoSrc && currentSrc && lastVideoSrc !== currentSrc) {
+                checkEpisodeTransition();
+            }
             setupListeners();
         }
     }
@@ -286,11 +461,15 @@
     const heartbeatInterval = setInterval(() => {
         const video = findVideo();
         if (video) {
+            const mediaTitle = (navigator.mediaSession && navigator.mediaSession.metadata) ? navigator.mediaSession.metadata.title : null;
             chrome.runtime.sendMessage({
                 type: 'HEARTBEAT',
                 payload: {
                     playbackState: video.paused ? 'paused' : 'playing',
-                    currentTime: video.currentTime
+                    currentTime: video.currentTime,
+                    mediaTitle: mediaTitle,
+                    volume: video.volume,
+                    muted: video.muted
                 }
             }).catch(err => {
                 if (err.message.includes('Extension context invalidated')) {
@@ -308,4 +487,12 @@
     // Initial Setup
     setupListeners();
 
+    // Episode Auto-Sync: Boot recovery — check if background has an active lobby
+    chrome.runtime.sendMessage({ type: 'CONTENT_BOOT' }, (res) => {
+        if (res && res.lobbyActive && res.expectedTitle) {
+            reportLog(`Boot: Active lobby detected for "${res.expectedTitle}"`, 'info');
+            startLobbyPoll(res.expectedTitle);
+        }
+    });
+
 })();

extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "KoalaSync",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "Synchronize video playback across different tabs and users.",
   "permissions": [
     "storage",
@@ -27,16 +27,6 @@
     "type": "module"
   },
   "content_scripts": [
-    {
-      "matches": [
-        "<all_urls>"
-      ],
-      "js": [
-        "content.js"
-      ],
-      "run_at": "document_idle",
-      "all_frames": false
-    },
     {
       "matches": ["https://koalasync.shik3i.net/*"],
       "js": ["bridge.js"],

extension/popup.html

@@ -148,9 +148,6 @@
         }
 
         .peer-item {
-            display: flex;
-            justify-content: space-between;
-            align-items: center;
             padding: 8px 0;
             border-bottom: 1px solid #334155;
         }
@@ -290,6 +287,16 @@
             <div style="text-align:center; color: var(--text-muted); font-size: 11px; padding-top: 20px;">No recent commands</div>
         </div>
 
+        <!-- Episode Auto-Sync Lobby Status -->
+        <div id="episodeLobbyCard" class="info-card" style="display:none; margin-bottom: 15px; border-left: 4px solid var(--star); animation: fadeIn 0.3s ease-out;">
+            <div style="display:flex; align-items:center; gap: 6px; margin-bottom: 6px;">
+                <span style="font-size: 16px;">⏳</span>
+                <span style="font-weight: 700; color: var(--star); font-size: 12px;">EPISODE LOBBY</span>
+            </div>
+            <div id="lobbyTitle" style="font-size: 11px; color: var(--text); margin-bottom: 6px; font-weight: 600;"></div>
+            <div id="lobbyPeerStatus" style="font-size: 10px; color: var(--text-muted);"></div>
+        </div>
+
         <div id="peerListSync" class="info-card" style="display:none;"></div>
     </div>
     
@@ -304,10 +311,16 @@
             <label style="margin-bottom: 0;">Filter Noise Tabs</label>
             <input type="checkbox" id="filterNoise" style="width: auto;" checked>
         </div>
+
+        <div class="form-group" style="display: flex; align-items: center; justify-content: space-between; background: var(--card); padding: 10px; border-radius: 8px; margin-bottom: 12px; border: 1px solid #334155;">
+            <label style="margin-bottom: 0;">Auto-Sync Next Episode</label>
+            <input type="checkbox" id="autoSyncNextEpisode" style="width: auto;">
+        </div>
         
         <div style="font-size: 11px; color: var(--text-muted); padding: 8px;">
             <p>• Username helps others identify you.</p>
             <p>• Noise filtering uses a blacklist to hide common non-video sites (e.g. Search, Social Media) from the Target Tab selector.</p>
+            <p>• Auto-Sync will pause and wait for all peers when an episode changes, then sync-start together.</p>
         </div>
 
         <div style="margin-top: 15px; padding: 8px; border-top: 1px solid var(--card);">
@@ -328,7 +341,7 @@
         </div>
 
         <label>Video Debug Info</label>
-        <div id="videoDebug" class="info-card" style="font-size: 10px; font-family: monospace; color: var(--text-muted); min-height: 60px; line-height: 1.4;">
+        <div id="videoDebug" class="info-card" style="font-size: 10px; font-family: monospace; color: var(--text-muted); max-height: 250px; overflow-y: auto; line-height: 1.4;">
             No tab selected or video detected.
         </div>
 
@@ -344,6 +357,11 @@
             <button id="clearLogs" style="background:transparent; border:none; color:var(--accent); font-size:10px; cursor:pointer;">CLEAR</button>
         </div>
         <div id="logList"></div>
+        
+        <div style="margin-top: 20px; text-align: center; border-top: 1px solid rgba(255,255,255,0.05); padding-top: 10px;">
+            <a href="https://github.com/Shik3i/KoalaSync" target="_blank" style="color: var(--text-muted); text-decoration: none; font-size: 10px; opacity: 0.6; display: block;">GitHub Repository</a>
+            <div id="appVersion" style="color: var(--text-muted); font-size: 9px; opacity: 0.4; margin-top: 4px;">v0.0.0</div>
+        </div>
     </div>
 
     <script src="popup.js" type="module"></script>

extension/popup.js

@@ -40,7 +40,11 @@ const elements = {
     peerListSync: document.getElementById('peerListSync'),
     videoDebug: document.getElementById('videoDebug'),
     playBtn: document.getElementById('playBtn'),
-    pauseBtn: document.getElementById('pauseBtn')
+    pauseBtn: document.getElementById('pauseBtn'),
+    autoSyncNextEpisode: document.getElementById('autoSyncNextEpisode'),
+    episodeLobbyCard: document.getElementById('episodeLobbyCard'),
+    lobbyTitle: document.getElementById('lobbyTitle'),
+    lobbyPeerStatus: document.getElementById('lobbyPeerStatus')
 };
 
 let localPeerId = null;
@@ -49,12 +53,19 @@ let lastPeersJson = null;
 // --- Initialization ---
 async function init() {
     // Load Settings
-    const data = await chrome.storage.sync.get(['serverUrl', 'useCustomServer', 'roomId', 'password', 'targetTabId', 'filterNoise', 'username']);
+    const data = await chrome.storage.sync.get(['serverUrl', 'useCustomServer', 'roomId', 'password', 'filterNoise', 'username', 'autoSyncNextEpisode']);
     elements.serverUrl.value = data.serverUrl || '';
     elements.roomId.value = data.roomId || '';
     elements.password.value = data.password || '';
     elements.username.value = data.username || '';
     elements.filterNoise.checked = data.filterNoise !== false;
+    elements.autoSyncNextEpisode.checked = !!data.autoSyncNextEpisode;
+    
+    // Set Version Info
+    const versionEl = document.getElementById('appVersion');
+    if (versionEl) {
+        versionEl.textContent = `v${chrome.runtime.getManifest().version}`;
+    }
 
     if (data.useCustomServer) {
         setServerMode(true);
@@ -62,21 +73,26 @@ async function init() {
         setServerMode(false);
     }
 
-    // Populate Tabs
-    await populateTabs();
-
     toggleUIState(!!data.roomId);
     updateUI(data.roomId, data.password, data.useCustomServer, data.serverUrl);
     refreshLogs();
     refreshHistory();
 
     // Initial Status Check
-    chrome.runtime.sendMessage({ type: 'GET_STATUS' }, (res) => {
+    chrome.runtime.sendMessage({ type: 'GET_STATUS' }, async (res) => {
         if (res) {
             localPeerId = res.peerId;
             applyConnectionStatus(res.status);
             updatePeerList(res.peers);
             if (res.lastActionState) updateLastActionUI(res.lastActionState, res.peers);
+            
+            // Populate Tabs using the background's targetTabId
+            await populateTabs(res.peers, res.targetTabId);
+
+            // Render lobby status if active
+            if (res.episodeLobby) updateLobbyUI(res.episodeLobby, res.peers);
+        } else {
+            await populateTabs();
         }
     });
 
@@ -94,6 +110,7 @@ async function init() {
 function toggleUIState(inRoom) {
     if (elements.sectionJoin) elements.sectionJoin.style.display = inRoom ? 'none' : 'block';
     if (elements.sectionActive) elements.sectionActive.style.display = inRoom ? 'block' : 'none';
+    if (elements.peerListSync) elements.peerListSync.style.display = inRoom ? 'block' : 'none';
 }
 
 function updateUI(roomId, password, useCustomServer = false, serverUrl = '') {
@@ -185,11 +202,56 @@ function updateLastActionUI(state, peers) {
     elements.lastActionCard.appendChild(grid);
 }
 
+function formatTime(seconds) {
+    if (seconds === null || seconds === undefined || isNaN(seconds)) return '--:--';
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    const s = Math.floor(seconds % 60);
+    if (h > 0) return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+    return `${m}:${String(s).padStart(2, '0')}`;
+}
+
+function getVolumeIcon(volume, muted) {
+    if (muted || volume === 0) return '🔇';
+    if (volume < 0.33) return '🔈';
+    if (volume < 0.66) return '🔉';
+    return '🔊';
+}
+
+let activePeers = [];
+let interpolationInterval = null;
+
+function startInterpolation() {
+    if (interpolationInterval) return;
+    interpolationInterval = setInterval(() => {
+        const timeElements = document.querySelectorAll('.peer-time-display');
+        timeElements.forEach(el => {
+            const peerId = el.dataset.peerId;
+            const peer = activePeers.find(p => p.peerId === peerId);
+            if (peer && peer.playbackState === 'playing' && peer.currentTime != null && peer.lastHeartbeat) {
+                const elapsed = (Date.now() - peer.lastHeartbeat) / 1000;
+                el.textContent = formatTime(peer.currentTime + elapsed);
+            }
+        });
+    }, 1000);
+}
+
 function updatePeerList(peers) {
     if (!peers) return;
+    activePeers = peers;
+    if (!interpolationInterval) startInterpolation();
     
-    // UI Throttle: Only re-render if the peer state actually changed
-    const currentPeersJson = JSON.stringify(peers);
+    // UI Throttle: Only re-render if the peer state actually changed (excluding time interpolation)
+    const stateToHash = peers.map(p => ({
+        id: p.peerId,
+        user: p.username,
+        tab: p.tabTitle,
+        media: p.mediaTitle,
+        state: p.playbackState,
+        vol: p.volume,
+        muted: p.muted
+    }));
+    const currentPeersJson = JSON.stringify(stateToHash);
     if (currentPeersJson === lastPeersJson) return;
     lastPeersJson = currentPeersJson;
 
@@ -210,10 +272,10 @@ function updatePeerList(peers) {
 
             const peerItem = document.createElement('div');
             peerItem.className = 'peer-item';
-            peerItem.style.cssText = 'display:block; padding: 6px 0;';
+            peerItem.style.cssText = 'position:relative; display:block; padding: 8px 0; border-bottom: 1px solid rgba(255,255,255,0.05);';
 
             const header = document.createElement('div');
-            header.style.cssText = 'display:flex; justify-content:space-between; align-items:center;';
+            header.style.cssText = 'display:flex; justify-content:space-between; align-items:center; padding-right: 24px;';
 
             const nameSpan = document.createElement('span');
             if (pUsername) {
@@ -232,22 +294,72 @@ function updatePeerList(peers) {
 
             header.appendChild(nameSpan);
 
+            // Volume Icon (Top Right)
+            if (p.volume !== undefined && p.volume !== null) {
+                const volIcon = document.createElement('div');
+                volIcon.style.cssText = 'position:absolute; top:8px; right:0; cursor:help; font-size:14px;';
+                volIcon.textContent = getVolumeIcon(p.volume, p.muted);
+                volIcon.title = p.muted ? 'Muted' : `Volume: ${Math.round(p.volume * 100)}%`;
+                peerItem.appendChild(volIcon);
+            }
+
             if (pId === localPeerId) {
                 const you = document.createElement('span');
-                you.style.cssText = 'font-size:10px; color:var(--accent)';
+                you.style.cssText = 'font-size:10px; color:var(--accent); font-weight:bold;';
                 you.textContent = 'YOU';
                 header.appendChild(you);
             }
 
             peerItem.appendChild(header);
 
-            if (pTabTitle) {
-                const titleDiv = document.createElement('div');
-                titleDiv.style.cssText = 'font-size:10px; color:var(--text-muted);';
-                titleDiv.textContent = pTabTitle;
-                peerItem.appendChild(titleDiv);
+            // Media Info
+            if (p.mediaTitle) {
+                const mediaDiv = document.createElement('div');
+                mediaDiv.style.cssText = 'font-size:11px; color:var(--star); font-weight: 600; margin-top: 2px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 280px;';
+                mediaDiv.textContent = `🎬 ${p.mediaTitle}`;
+                peerItem.appendChild(mediaDiv);
             }
 
+            // Status Line (Play/Pause + Time)
+            const statusLine = document.createElement('div');
+            statusLine.style.cssText = 'display:flex; align-items:center; gap:8px; margin-top:4px;';
+
+            if (p.playbackState) {
+                const stateIcon = document.createElement('span');
+                stateIcon.style.fontSize = '10px';
+                if (p.playbackState === 'playing') {
+                    stateIcon.textContent = '▶';
+                    stateIcon.style.color = 'var(--success)';
+                } else {
+                    stateIcon.textContent = '⏸';
+                    stateIcon.style.color = 'var(--error)';
+                }
+                statusLine.appendChild(stateIcon);
+            }
+
+            if (p.currentTime !== undefined && p.currentTime !== null) {
+                const timeSpan = document.createElement('span');
+                timeSpan.className = 'peer-time-display';
+                timeSpan.dataset.peerId = pId;
+                timeSpan.style.cssText = 'font-size:11px; font-family:monospace; color:var(--text-muted);';
+                
+                let displayTime = p.currentTime;
+                if (p.playbackState === 'playing' && p.lastHeartbeat && p.currentTime != null) {
+                    const elapsed = (Date.now() - p.lastHeartbeat) / 1000;
+                    displayTime += elapsed;
+                }
+                timeSpan.textContent = formatTime(displayTime);
+                statusLine.appendChild(timeSpan);
+            }
+
+            if (pTabTitle) {
+                const titleDiv = document.createElement('span');
+                titleDiv.style.cssText = 'font-size:10px; color:var(--text-muted); opacity: 0.6; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; flex: 1; text-align: right;';
+                titleDiv.textContent = pTabTitle;
+                statusLine.appendChild(titleDiv);
+            }
+
+            peerItem.appendChild(statusLine);
             container.appendChild(peerItem);
         });
     };
@@ -259,10 +371,16 @@ function updatePeerList(peers) {
     populateTabs(peers);
 }
 
-async function populateTabs(providedPeers = null) {
-    const data = await chrome.storage.sync.get(['targetTabId', 'filterNoise']);
+async function populateTabs(providedPeers = null, providedTargetTabId = null) {
+    const data = await chrome.storage.sync.get(['filterNoise']);
     const isFilterActive = data.filterNoise !== false;
-    const currentTargetTabId = data.targetTabId;
+    
+    // Fallback if not provided directly
+    let currentTargetTabId = providedTargetTabId;
+    if (currentTargetTabId === null) {
+        const status = await new Promise(r => chrome.runtime.sendMessage({ type: 'GET_STATUS' }, r));
+        currentTargetTabId = status?.targetTabId;
+    }
  
     // Use provided peers or fetch if missing
     let peerIds = providedPeers;
@@ -520,6 +638,10 @@ elements.filterNoise.addEventListener('change', () => {
     });
 });
 
+elements.autoSyncNextEpisode.addEventListener('change', () => {
+    chrome.storage.sync.set({ autoSyncNextEpisode: elements.autoSyncNextEpisode.checked });
+});
+
 elements.serverUrl.addEventListener('input', () => {
     chrome.storage.sync.set({ serverUrl: elements.serverUrl.value });
 });
@@ -638,15 +760,18 @@ elements.retryBtn.addEventListener('click', () => {
     chrome.runtime.sendMessage({ type: 'RETRY_CONNECT' });
 });
 
-elements.targetTab.addEventListener('change', async () => {
-    await chrome.storage.sync.set({ targetTabId: elements.targetTab.value });
+elements.targetTab.addEventListener('change', () => {
+    const val = elements.targetTab.value;
+    const tabId = val ? parseInt(val) : null;
+    const tabTitle = elements.targetTab.options[elements.targetTab.selectedIndex]?.text.replace('⭐ MATCH: ', '') || null;
+    chrome.runtime.sendMessage({ type: 'SET_TARGET_TAB', tabId, tabTitle });
 });
 
 elements.forceSyncBtn.addEventListener('click', async () => {
     if (elements.forceSyncBtn.disabled) return;
     
-    const settings = await chrome.storage.sync.get(['targetTabId']);
-    if (!settings.targetTabId) return;
+    const status = await new Promise(r => chrome.runtime.sendMessage({ type: 'GET_STATUS' }, r));
+    if (!status || !status.targetTabId) return;
 
     // Lockout to prevent spamming
     const originalText = elements.forceSyncBtn.textContent;
@@ -657,7 +782,7 @@ elements.forceSyncBtn.addEventListener('click', async () => {
         elements.forceSyncBtn.textContent = originalText;
     }, 5000);
 
-    const tabId = parseInt(settings.targetTabId);
+    const tabId = parseInt(status.targetTabId);
 
     const sendForceSync = (time) => {
         chrome.runtime.sendMessage({
@@ -770,6 +895,15 @@ chrome.runtime.onMessage.addListener((msg) => {
             // Join failed: reset UI state
             updateUI(null, null);
         }
+    } else if (msg.type === 'LOBBY_UPDATE') {
+        // Episode lobby state changed
+        chrome.runtime.sendMessage({ type: 'GET_STATUS' }, (res) => {
+            if (res && res.peers) {
+                updateLobbyUI(msg.lobby, res.peers);
+            } else {
+                updateLobbyUI(msg.lobby, []);
+            }
+        });
     }
 });
 
@@ -806,31 +940,57 @@ function refreshDebugInfo() {
             if (elements.videoDebug) {
                 elements.videoDebug.innerHTML = '';
                 
-                const status = document.createElement('div');
-                status.style.cssText = 'color:var(--accent); margin-bottom:4px;';
-                status.textContent = `VIDEO STATE: ${state.paused ? 'PAUSED' : 'PLAYING'}`;
+                const addField = (label, value, color = null) => {
+                    const row = document.createElement('div');
+                    row.style.marginBottom = '4px';
+                    if (color) row.style.color = color;
+                    
+                    const b = document.createElement('b');
+                    b.textContent = `${label}: `;
+                    b.style.color = 'var(--text-muted)';
+                    
+                    const span = document.createElement('span');
+                    span.textContent = value;
+                    span.style.wordBreak = 'break-all';
+                    
+                    row.appendChild(b);
+                    row.appendChild(span);
+                    elements.videoDebug.appendChild(row);
+                };
+
+                const addSection = (title) => {
+                    const div = document.createElement('div');
+                    div.style.cssText = 'margin: 8px 0 4px 0; border-bottom: 1px solid #334155; padding-bottom: 2px; color: var(--accent); font-weight: bold; font-size: 9px;';
+                    div.textContent = title.toUpperCase();
+                    elements.videoDebug.appendChild(div);
+                };
+
+                addField('STATE', state.paused ? 'PAUSED' : 'PLAYING', 'var(--accent)');
+                addField('TIME', `${state.currentTime.toFixed(2)}s / ${state.duration.toFixed(2)}s`);
+                addField('READY', state.readyState);
                 
-                const time = document.createElement('div');
-                time.style.fontSize = '11px';
-                time.textContent = `Time: ${state.currentTime.toFixed(2)}s / ${state.duration.toFixed(2)}s`;
+                addSection('Identification');
+                addField('URL', state.url);
+                addField('ID', state.id);
+                addField('CLASS', state.className);
                 
-                const readyState = document.createElement('div');
-                readyState.style.fontSize = '11px';
-                readyState.textContent = `ReadyState: ${state.readyState}`;
-                
-                const misc = document.createElement('div');
-                misc.style.fontSize = '11px';
-                misc.textContent = `Muted: ${state.muted} | PlaybackRate: ${state.playbackRate}`;
-                
-                const url = document.createElement('div');
-                url.style.cssText = 'font-size:9px; margin-top:4px; opacity:0.7;';
-                url.textContent = `URL: ${state.url.substring(0, 40)}...`;
-                
-                elements.videoDebug.appendChild(status);
-                elements.videoDebug.appendChild(time);
-                elements.videoDebug.appendChild(readyState);
-                elements.videoDebug.appendChild(misc);
-                elements.videoDebug.appendChild(url);
+                addSection('Media Source');
+                addField('CURRENT_SRC', state.currentSrc);
+                addField('SRC', state.src);
+
+                if (state.metadata) {
+                    addSection('Media Session API');
+                    addField('TITLE', state.metadata.title || 'n/a');
+                    addField('ARTIST', state.metadata.artist || 'n/a');
+                    addField('ALBUM', state.metadata.album || 'n/a');
+                }
+
+                if (state.dataAttributes && Object.keys(state.dataAttributes).length > 0) {
+                    addSection('Data Attributes');
+                    for (const [key, val] of Object.entries(state.dataAttributes)) {
+                        addField(key.replace('data-', '').toUpperCase(), val);
+                    }
+                }
             }
         });
     });
@@ -838,3 +998,43 @@ function refreshDebugInfo() {
 
 init();
 setInterval(refreshLogs, 5000);
+
+// --- Episode Lobby UI ---
+function updateLobbyUI(lobby, peers) {
+    if (!elements.episodeLobbyCard) return;
+
+    if (!lobby) {
+        elements.episodeLobbyCard.style.display = 'none';
+        return;
+    }
+
+    elements.episodeLobbyCard.style.display = 'block';
+    elements.lobbyTitle.textContent = `\u{1F3AC} Waiting for: "${lobby.expectedTitle}"`;
+
+    // Build peer readiness list
+    const readySet = new Set(lobby.readyPeers || []);
+    const peerLines = [];
+
+    if (peers && peers.length > 0) {
+        peers.forEach(p => {
+            const pId = typeof p === 'object' ? p.peerId : p;
+            const pName = (typeof p === 'object' && p.username) ? p.username : pId;
+            const isReady = readySet.has(pId);
+            const icon = isReady ? '\u2705' : '\u23f3';
+            const label = isReady ? 'Ready' : 'Loading...';
+            peerLines.push(`${icon} ${pName} \u2014 ${label}`);
+        });
+    }
+
+    if (peerLines.length > 0) {
+        elements.lobbyPeerStatus.textContent = peerLines.join(' | ');
+    } else {
+        elements.lobbyPeerStatus.textContent = 'Waiting for peers...';
+    }
+
+    // Show elapsed time
+    if (lobby.createdAt) {
+        const elapsed = Math.floor((Date.now() - lobby.createdAt) / 1000);
+        elements.lobbyPeerStatus.textContent += ` (${elapsed}s)`;
+    }
+}

extension/shared/README.md

@@ -0,0 +1,14 @@
+# ⚠️ READ BEFORE EDITING
+
+This directory is a **MIRROR** of the root `/shared` folder.
+
+**DO NOT edit these files directly.** Any changes made here will be overwritten the next time the synchronization script is run.
+
+### Proper Workflow:
+1.  **Edit** the source files in the root `[repo_root]/shared/` directory.
+2.  **Run** the synchronization script:
+    -   **Windows**: `[repo_root]\scripts\sync-constants.bat`
+    -   **Linux/macOS**: `[repo_root]/scripts/sync-constants.sh`
+3.  **Verify** that the changes have propagated to this folder.
+
+Failure to follow this protocol will result in out-of-sync components and broken protocol logic.

server/index.js

@@ -23,7 +23,7 @@ const httpServer = createServer(app);
 // Socket.IO setup with security constraints
 const io = new Server(httpServer, {
     cors: {
-        origin: "*",
+        origin: ["https://koalasync.shik3i.net"],
         methods: ["GET", "POST"]
     },
     maxHttpBufferSize: 1024, // 1KB max per message
@@ -113,6 +113,51 @@ function checkEventRate(socketId) {
     return entry.count <= 30;
 }
 
+/**
+ * Central peer teardown. Removes a socket from all room state and notifies
+ * remaining peers. Call this from every disconnect/leave/reaper/dedupe path.
+ *
+ * @param {string}  socketId   - The socket.id being removed.
+ * @param {string}  roomId     - The room it belongs to.
+ * @param {string}  reason     - Log label ('disconnect', 'leave', 'reaper', 'dedupe', 'room-switch').
+ * @param {boolean} [emitLeave=true] - Set false when the socket.io room leave
+ *                                     is handled by the caller (e.g. reaper calls
+ *                                     socket.leave() before us, or dedupe calls
+ *                                     oldSocket.leave() before disconnecting).
+ */
+function removePeerFromRoom(socketId, roomId, reason, emitLeave = true) {
+    const room = rooms.get(roomId);
+    if (!room) return;
+
+    const peerData = room.peerData.get(socketId);
+    if (!peerData) return; // Already cleaned up
+
+    const { peerId } = peerData;
+
+    // 1. Remove from room data structures
+    room.peers.delete(socketId);
+    room.peerIds.delete(socketId);
+    room.peerData.delete(socketId);
+
+    // 2. Remove from global maps
+    socketToRoom.delete(socketId);
+    if (peerToSocket.get(peerId) === socketId) {
+        peerToSocket.delete(peerId);
+    }
+
+    // 3. Notify remaining peers (use io.to so the removed socket itself
+    //    doesn't receive it — it has already left or is disconnecting)
+    io.to(roomId).emit(EVENTS.PEER_STATUS, { peerId, status: 'left' });
+
+    // 4. Delete empty room
+    if (room.peers.size === 0) {
+        rooms.delete(roomId);
+        log('ROOM', `Deleted empty room after ${reason}: ${roomId.substring(0, 3)}***`);
+    }
+
+    log('ROOM', `Peer ${peerId} removed (${reason}) from room ${roomId.substring(0, 3)}***`);
+}
+
 io.on('connection', (socket) => {
     const clientIp = socket.handshake.address;
     
@@ -155,7 +200,16 @@ io.on('connection', (socket) => {
             return;
         }
         if (!payload || typeof payload.roomId !== 'string') return;
-        const { roomId, password, peerId, username, tabTitle, protocolVersion } = payload;
+        const { password, peerId, protocolVersion } = payload;
+
+        // --- M-2: Sanitize and clamp all string fields ---
+        const roomId   = String(payload.roomId   || '').substring(0, 64);
+        const username = typeof payload.username  === 'string' ? payload.username.substring(0, 30)  : null;
+        const tabTitle = typeof payload.tabTitle  === 'string' ? payload.tabTitle.substring(0, 100) : null;
+        const mediaTitle = typeof payload.mediaTitle === 'string' ? payload.mediaTitle.substring(0, 100) : null;
+
+        if (!roomId) return; // Guard: empty after sanitization
+
         try {
             // Protocol check
             if (protocolVersion !== '1.0.0') {
@@ -171,14 +225,7 @@ io.on('connection', (socket) => {
             }
             if (oldMapping && oldMapping.roomId !== roomId) {
                 socket.leave(oldMapping.roomId);
-                const oldRoom = rooms.get(oldMapping.roomId);
-                if (oldRoom) {
-                    oldRoom.peers.delete(socket.id);
-                    oldRoom.peerIds.delete(socket.id);
-                    oldRoom.peerData.delete(socket.id);
-                    socket.to(oldMapping.roomId).emit(EVENTS.PEER_STATUS, { peerId: oldMapping.peerId, status: 'left' });
-                    if (oldRoom.peers.size === 0) rooms.delete(oldMapping.roomId);
-                }
+                removePeerFromRoom(socket.id, oldMapping.roomId, 'room-switch');
             }
 
             const ip = socket.handshake.address;
@@ -228,11 +275,7 @@ io.on('connection', (socket) => {
                             oldSocket.disconnect(true);
                             log('DEDUPE', `Kicked old session for peer ${peerId}`);
                         }
-                        room.peers.delete(sid);
-                        room.peerIds.delete(sid);
-                        room.peerData.delete(sid);
-                        socket.to(roomId).emit(EVENTS.PEER_STATUS, { peerId: data.peerId, status: 'left' });
-                        log('ROOM', `Deduplicated peer ${peerId} from room ${roomId}`);
+                        removePeerFromRoom(sid, roomId, 'dedupe');
                     }
                 }
             }
@@ -244,12 +287,13 @@ io.on('connection', (socket) => {
                 peerId, 
                 username: username || null, 
                 tabTitle: tabTitle || null,
+                mediaTitle: mediaTitle || null,
                 lastSeen: Date.now() 
             });
             socketToRoom.set(socket.id, { roomId, peerId });
             peerToSocket.set(peerId, socket.id);
 
-            socket.to(roomId).emit(EVENTS.PEER_STATUS, { peerId, username: username || null, tabTitle: tabTitle || null, status: 'joined' });
+            socket.to(roomId).emit(EVENTS.PEER_STATUS, { peerId, username: username || null, tabTitle: tabTitle || null, mediaTitle: mediaTitle || null, status: 'joined' });
             socket.emit(EVENTS.ROOM_DATA, { 
                 roomId, 
                 peers: Array.from(room.peers).map(sid => room.peerData.get(sid)) 
@@ -265,7 +309,8 @@ io.on('connection', (socket) => {
     const relayEvents = [
         EVENTS.PLAY, EVENTS.PAUSE, EVENTS.SEEK, 
         EVENTS.PEER_STATUS, EVENTS.FORCE_SYNC_PREPARE, 
-        EVENTS.FORCE_SYNC_ACK, EVENTS.FORCE_SYNC_EXECUTE
+        EVENTS.FORCE_SYNC_ACK, EVENTS.FORCE_SYNC_EXECUTE,
+        EVENTS.EPISODE_LOBBY, EVENTS.EPISODE_READY
     ];
 
     relayEvents.forEach(eventName => {
@@ -285,11 +330,19 @@ io.on('connection', (socket) => {
                     room.lastActivity = Date.now();
                     
                     // Update peer metadata and lastSeen
+                    // Sanitize mutable string fields to enforce the same length
+                    // limits as JOIN_ROOM — the relay path is otherwise unbounded.
+                    const clamp = (val, max) => typeof val === 'string' ? val.substring(0, max) : val;
                     const existing = room.peerData.get(socket.id) || { peerId: mapping.peerId };
                     room.peerData.set(socket.id, { 
                         ...existing,
-                        username: data.username || existing.username,
-                        tabTitle: data.tabTitle || existing.tabTitle,
+                        username:      data.username      !== undefined ? clamp(data.username, 30)   : existing.username,
+                        tabTitle:      data.tabTitle      !== undefined ? clamp(data.tabTitle, 100)  : existing.tabTitle,
+                        mediaTitle:    data.mediaTitle    !== undefined ? clamp(data.mediaTitle, 100) : existing.mediaTitle,
+                        playbackState: data.playbackState !== undefined ? data.playbackState          : existing.playbackState,
+                        currentTime:   data.currentTime   !== undefined ? data.currentTime            : existing.currentTime,
+                        volume:        data.volume        !== undefined ? data.volume                 : existing.volume,
+                        muted:         data.muted         !== undefined ? data.muted                  : existing.muted,
                         lastSeen: Date.now()
                     });
 
@@ -311,23 +364,8 @@ io.on('connection', (socket) => {
     socket.on(EVENTS.LEAVE_ROOM, () => {
         const mapping = socketToRoom.get(socket.id);
         if (mapping) {
-            const { roomId, peerId } = mapping;
-            socket.leave(roomId);
-            const room = rooms.get(roomId);
-            if (room) {
-                room.peers.delete(socket.id);
-                room.peerIds.delete(socket.id);
-                room.peerData.delete(socket.id);
-                socket.to(roomId).emit(EVENTS.PEER_STATUS, { peerId, status: 'left' });
-                if (room.peers.size === 0) {
-                    rooms.delete(roomId);
-                    log('ROOM', `Deleted empty room: ${roomId.substring(0, 3)}***`);
-                }
-            }
-            socketToRoom.delete(socket.id);
-            if (peerToSocket.get(peerId) === socket.id) {
-                peerToSocket.delete(peerId);
-            }
+            socket.leave(mapping.roomId);
+            removePeerFromRoom(socket.id, mapping.roomId, 'leave');
         }
     });
 
@@ -353,22 +391,10 @@ io.on('connection', (socket) => {
         eventCounts.delete(socket.id);
         const mapping = socketToRoom.get(socket.id);
         if (mapping) {
-            const { roomId, peerId } = mapping;
-            const room = rooms.get(roomId);
-            if (room) {
-                room.peers.delete(socket.id);
-                room.peerIds.delete(socket.id);
-                room.peerData.delete(socket.id);
-                socket.to(roomId).emit(EVENTS.PEER_STATUS, { peerId, status: 'left' });
-                if (room.peers.size === 0) {
-                    rooms.delete(roomId);
-                    log('ROOM', `Deleted empty room (after disconnect): ${roomId.substring(0, 3)}***`);
-                }
-            }
-            socketToRoom.delete(socket.id);
-            if (peerToSocket.get(peerId) === socket.id) {
-                peerToSocket.delete(peerId);
-            }
+            // Socket is already disconnected — no need to call socket.leave().
+            // removePeerFromRoom uses io.to() for notifications, which correctly
+            // excludes this dead socket since it has already left all rooms.
+            removePeerFromRoom(socket.id, mapping.roomId, 'disconnect');
         }
     });
 });
@@ -381,23 +407,21 @@ setInterval(() => {
     
     for (const [roomId, room] of rooms) {
         // 1. Prune dead peers
+        // Snapshot keys first — we must not mutate peerData while iterating it.
+        const staleSids = [];
         for (const [sid, data] of room.peerData.entries()) {
             if (data.lastSeen && data.lastSeen < peerCutoff) {
-                const socket = io.sockets.sockets.get(sid);
-                if (socket) socket.leave(roomId);
-                
-                room.peers.delete(sid);
-                room.peerIds.delete(sid);
-                room.peerData.delete(sid);
-                socketToRoom.delete(sid);
-                if (peerToSocket.get(data.peerId) === sid) {
-                    peerToSocket.delete(data.peerId);
-                }
-                
-                io.to(roomId).emit(EVENTS.PEER_STATUS, { peerId: data.peerId, status: 'left' });
-                log('CLEANUP', `Pruned dead peer ${data.peerId} from room ${roomId}`);
+                staleSids.push(sid);
             }
         }
+        for (const sid of staleSids) {
+            // Gracefully evict the socket from the Socket.IO room if it is
+            // still technically connected (zombie with no heartbeat).
+            const deadSocket = io.sockets.sockets.get(sid);
+            if (deadSocket) deadSocket.leave(roomId);
+            log('CLEANUP', `Pruning dead peer from room ${roomId.substring(0, 3)}***`);
+            removePeerFromRoom(sid, roomId, 'reaper');
+        }
 
         // 2. Prune empty or inactive rooms
         if (room.peers.size === 0 || room.lastActivity < roomCutoff) {
@@ -411,3 +435,23 @@ setInterval(() => {
 httpServer.listen(PORT, () => {
     log('SERVER', `KoalaSync Relay running on port ${PORT}`);
 });
+
+// --- M-4: Graceful Shutdown ---
+function gracefulShutdown(signal) {
+    log('SERVER', `${signal} received — starting graceful shutdown...`);
+    // 1. Notify all connected clients so they can display a meaningful message
+    io.emit(EVENTS.ERROR, { message: 'Server is restarting. Please reconnect in a moment.' });
+    // 2. Stop accepting new HTTP connections
+    httpServer.close(() => {
+        log('SERVER', 'HTTP server closed. Exiting.');
+        process.exit(0);
+    });
+    // 3. Safety net: force-exit after 5s if connections don't drain
+    setTimeout(() => {
+        log('SERVER', 'Force-exit after timeout.');
+        process.exit(1);
+    }, 5000);
+}
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT',  () => gracefulShutdown('SIGINT'));

shared/blacklist.js

@@ -1,6 +1,10 @@
 /**
  * blacklist.js
  * 
+ * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH.
+ * If you edit this file, you MUST run /scripts/sync-constants.bat 
+ * to propagate changes to the extension and relay server.
+ * 
  * Domains to be filtered out from the tab selection dropdown to reduce "noise".
  * These are typically sites that won't contain shareable video content.
  */

shared/constants.js

@@ -1,9 +1,13 @@
 /**
  * KoalaSync Shared Constants & Protocol Definitions
+ * 
+ * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH.
+ * If you edit this file, you MUST run /scripts/sync-constants.bat 
+ * to propagate changes to the extension and relay server.
  */
 
 export const PROTOCOL_VERSION = "1.0.0";
-export const APP_VERSION = "1.0.3";
+export const APP_VERSION = "1.2.0";
 
 export const OFFICIAL_SERVER_URL = 'wss://sync.shik3i.net';
 export const OFFICIAL_LANDING_PAGE_URL = 'https://koalasync.shik3i.net';
@@ -28,8 +32,13 @@ export const EVENTS = {
     FORCE_SYNC_EXECUTE: "force_sync_execute",
     EVENT_ACK: "event_ack",
     GET_ROOMS: "get_rooms",
-    ROOM_LIST: "room_list"
+    ROOM_LIST: "room_list",
+
+    // Episode Auto-Sync
+    EPISODE_LOBBY: "episode_lobby",     // Broadcast: waiting for everyone on this episode
+    EPISODE_READY: "episode_ready"      // Response: loaded the episode and paused at 0:00
 };
 
 export const HEARTBEAT_INTERVAL = 15000; // 15s
 export const FORCE_SYNC_TIMEOUT = 5000; // 5s timeout for ACKs
+export const EPISODE_LOBBY_TIMEOUT = 60000; // 60s timeout for episode lobby

website/app.js

@@ -104,12 +104,26 @@ document.addEventListener('DOMContentLoaded', () => {
                             const banner = document.createElement('div');
                             banner.className = 'invite-banner';
                             banner.id = 'koala-banner';
-                            banner.innerHTML = `
-                                <div class="container" style="display:flex; justify-content:space-between; align-items:center;">
-                                    <span>🎫 Invitation for <b>${roomId}</b> detected!</span>
-                                    <a href="join.html${window.location.hash}" class="btn-banner">OPEN JOIN PAGE</a>
-                                </div>
-                            `;
+
+                            const container = document.createElement('div');
+                            container.className = 'container';
+                            container.style.cssText = 'display:flex; justify-content:space-between; align-items:center;';
+
+                            const inviteSpan = document.createElement('span');
+                            inviteSpan.appendChild(document.createTextNode('🎫 Invitation for '));
+                            const boldRoom = document.createElement('b');
+                            boldRoom.textContent = roomId;
+                            inviteSpan.appendChild(boldRoom);
+                            inviteSpan.appendChild(document.createTextNode(' detected!'));
+
+                            const joinLink = document.createElement('a');
+                            joinLink.href = 'join.html' + window.location.hash;
+                            joinLink.className = 'btn-banner';
+                            joinLink.textContent = 'OPEN JOIN PAGE';
+
+                            container.appendChild(inviteSpan);
+                            container.appendChild(joinLink);
+                            banner.appendChild(container);
                             document.body.prepend(banner);
                         }
                     }
@@ -178,7 +192,11 @@ document.addEventListener('DOMContentLoaded', () => {
                     setTimeout(() => window.close(), 3000);
                 } else {
                     banner.style.background = 'var(--error)';
-                    banner.innerHTML = `<div class="container">❌ Error: ${message}</div>`;
+                    banner.innerHTML = '';
+                    const errDiv = document.createElement('div');
+                    errDiv.className = 'container';
+                    errDiv.textContent = '❌ Error: ' + message;
+                    banner.appendChild(errDiv);
                 }
             }
         }

website/index.html

@@ -38,6 +38,7 @@
     <header class="hero">
         <div class="container hero-grid">
             <div class="hero-text">
+                <div class="version-badge" data-reveal>v1.2.0 OUT NOW</div>
                 <h1 data-reveal>Watch Together.<br>Sync Perfectly.</h1>
                 <p data-reveal>KoalaSync brings friends closer through synchronized video playback. No lag, no tracking, just shared moments.</p>
                 <div class="cta-group" data-reveal>
@@ -64,6 +65,11 @@
                     <h3>Real-time Sync</h3>
                     <p>Proprietary two-phase synchronization protocol ensures sub-millisecond precision across all peers.</p>
                 </div>
+                <div class="feature-card" data-reveal>
+                    <div class="feature-icon">🎬</div>
+                    <h3>Episode Auto-Sync</h3>
+                    <p>New in v1.2.0: Perfectly sync series binges. All peers wait until everyone has loaded the next episode.</p>
+                </div>
                 <div class="feature-card" data-reveal>
                     <div class="feature-icon">🛡️</div>
                     <h3>Privacy First</h3>
@@ -75,6 +81,7 @@
                     <p>Find the right tab instantly. KoalaSync highlights and sorts matching video tabs for you.</p>
                 </div>
             </div>
+
         </div>
     </section>
 

website/style.css

@@ -223,6 +223,21 @@ nav {
     transform: translateY(-2px);
 }
 
+.version-badge {
+    display: inline-block;
+    background: rgba(99, 102, 241, 0.1);
+    color: var(--accent);
+    padding: 0.5rem 1.25rem;
+    border-radius: 99px;
+    font-size: 0.85rem;
+    font-weight: 700;
+    margin-bottom: 1.5rem;
+    border: 1px solid rgba(99, 102, 241, 0.3);
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+}
+
+
 .hero-image {
     display: none;
 }