chore: bump version to 1.1.0

.github/workflows/release.yml

@@ -51,6 +51,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Sync Protocol Constants
+        run: |
+          chmod +x ./scripts/sync-constants.sh
+          ./scripts/sync-constants.sh
+
       - name: Create Extension Zip
         run: |
           zip -r koala-sync-extension.zip extension/ -x "*.DS_Store*"

.gitignore

@@ -39,3 +39,6 @@ coverage/
 # We ignore the synced files in the extension folder to ensure 
 # the root 'shared/' remains the Single Source of Truth.
 extension/shared/
+
+# Temporary scratch files
+scratch/

README.md

@@ -8,11 +8,17 @@ KoalaSync is a premium, lightweight Chrome Extension and Relay Server for synchr
 ## Repository Structure
 - `extension/`: Chrome Extension (Manifest V3, Vanilla JS).
 - `server/`: Node.js + Socket.IO Relay Server (Containerized).
-- `website/`: Static marketing landing page & tutorials.
-- `shared/`: Shared protocol constants.
+- `website/`: Marketing landing page & **Invitation Bridge**.
+- `shared/`: Protocol constants and domain blacklist.
+- `scripts/`: Development utilities for protocol synchronization.
+
+> [!NOTE]
+> For deep technical dives, see [ARCHITECTURE.md](ARCHITECTURE.md) and [SYNC_GUIDE.md](SYNC_GUIDE.md).
 
 ## Key Features
 - **Global Synchronization**: Synchronize Play, Pause, and Seeking on any website with a `<video>` tag.
+- **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.
 - **Dual Heartbeat Architecture**: Robust session tracking that prevents ghost rooms and stale connections.
 - **Zero-Latency Relay**: Custom Socket.IO wire protocol implementation for maximum performance.
@@ -31,10 +37,14 @@ docker-compose up -d --build
 The server will be available at `ws://localhost:3000`.
 
 ### 2. Chrome Extension
-1. Open Chrome and go to `chrome://extensions/`.
-2. Enable **Developer mode** (top right).
-3. Click **Load unpacked**.
-4. Select the `extension/` folder.
+1. **Synchronize Protocol**: From the root directory, run the sync script to copy the master constants to the extension folder:
+   ```bash
+   ./scripts/sync-constants.sh
+   ```
+2. Open Chrome and go to `chrome://extensions/`.
+3. Enable **Developer mode** (top right).
+4. Click **Load unpacked**.
+5. Select the `extension/` folder.
 
 ## Usage
 1. Open the extension and go to the **Settings** tab to set your **Username**.

SYNC_GUIDE.md

@@ -7,10 +7,11 @@ To ensure that the extension and the relay server are always using the exact sam
 
 ## When should you run the sync script?
 You MUST run the synchronization script in any of the following scenarios:
-1. **After modifying** `shared/constants.js`.
-2. **After modifying** `shared/blacklist.js`.
-3. **Before committing** changes to the repository if any protocol-related files were touched.
-4. **Before deploying** the server or releasing the extension.
+1. **After a fresh `git clone` or `git pull`** (as the synced files are ignored by git).
+2. **After modifying** `shared/constants.js`.
+3. **After modifying** `shared/blacklist.js`.
+4. **Before committing** changes to the repository if any protocol-related files were touched.
+5. **Before deploying** the server or releasing the extension.
 
 ## How to sync
 

extension/README.md

@@ -22,9 +22,10 @@ KoalaSync requires `<all_urls>` permission to detect and interact with video ele
 - **Zero Telemetry**: No analytics or external tracking scripts.
 
 ## Installation
-1. Open Chrome and go to `chrome://extensions/`.
-2. Enable **Developer mode** (top right).
-3. Click **Load unpacked** and select the `extension` folder from this repository.
+1. **Sync Protocol**: Run `./scripts/sync-constants.sh` (macOS/Linux) or `scripts\sync-constants.bat` (Windows) from the root.
+2. Open Chrome and go to `chrome://extensions/`.
+3. Enable **Developer mode** (top right).
+4. Click **Load unpacked** and select the `extension` folder.
 
 ## Development
 If you modify `shared/constants.js`, you must synchronize the changes across the extension and server:

extension/content.js

@@ -55,6 +55,15 @@
         const video = findVideo();
         if (!video) return;
 
+        if (action === EVENTS.SEEK) {
+            const target = data ? (data.targetTime !== undefined ? data.targetTime : data.currentTime) : undefined;
+            if (!Number.isFinite(target)) {
+                reportLog(`Media Action Error: Invalid seek payload - ${JSON.stringify(data)}`, 'error');
+                return;
+            }
+            data.targetTime = target;
+        }
+
         try {
             const host = window.location.hostname.toLowerCase();
             const isYouTube = host.includes('youtube.com');
@@ -162,6 +171,10 @@
                 if (!payload || payload.targetTime === undefined) return;
                 const video = findVideo();
                 if (video) {
+                    if (!Number.isFinite(payload.targetTime)) {
+                        reportLog(`Media Action Error: Invalid force sync payload - ${JSON.stringify(payload)}`, 'error');
+                        return;
+                    }
                     setTargetState('paused');
                     video.pause();
                     video.currentTime = payload.targetTime;
@@ -178,6 +191,22 @@
         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,
@@ -186,7 +215,12 @@
                     muted: video.muted,
                     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' });
@@ -199,6 +233,11 @@
         const video = findVideo();
         if (!video) return;
 
+        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) {
@@ -210,7 +249,9 @@
             type: 'CONTENT_EVENT',
             action,
             payload: {
-                currentTime: video.currentTime,
+                currentTime: current,
+                targetTime: current,
+                mediaTitle: mediaTitle,
                 timestamp: Date.now()
             }
         });
@@ -269,11 +310,13 @@
     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
                 }
             }).catch(err => {
                 if (err.message.includes('Extension context invalidated')) {

extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "KoalaSync",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Synchronize video playback across different tabs and users.",
   "permissions": [
     "storage",

extension/popup.html

@@ -328,7 +328,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>
 

extension/popup.js

@@ -241,10 +241,17 @@ function updatePeerList(peers) {
 
             peerItem.appendChild(header);
 
+            if (p.mediaTitle) {
+                const mediaDiv = document.createElement('div');
+                mediaDiv.style.cssText = 'font-size:11px; color:var(--star); font-weight: 600; margin-top: 2px;';
+                mediaDiv.textContent = `🎬 ${p.mediaTitle}`;
+                peerItem.appendChild(mediaDiv);
+            }
+
             if (pTabTitle) {
                 const titleDiv = document.createElement('div');
-                titleDiv.style.cssText = 'font-size:10px; color:var(--text-muted);';
-                titleDiv.textContent = pTabTitle;
+                titleDiv.style.cssText = 'font-size:10px; color:var(--text-muted); opacity: 0.8;';
+                titleDiv.textContent = p.mediaTitle ? `via ${pTabTitle}` : pTabTitle;
                 peerItem.appendChild(titleDiv);
             }
 
@@ -806,31 +813,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);
+                    }
+                }
             }
         });
     });

server/index.js

@@ -155,7 +155,7 @@ io.on('connection', (socket) => {
             return;
         }
         if (!payload || typeof payload.roomId !== 'string') return;
-        const { roomId, password, peerId, username, tabTitle, protocolVersion } = payload;
+        const { roomId, password, peerId, username, tabTitle, mediaTitle, protocolVersion } = payload;
         try {
             // Protocol check
             if (protocolVersion !== '1.0.0') {
@@ -244,12 +244,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)) 
@@ -288,8 +289,9 @@ io.on('connection', (socket) => {
                     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 ? data.username : existing.username,
+                        tabTitle: data.tabTitle !== undefined ? data.tabTitle : existing.tabTitle,
+                        mediaTitle: data.mediaTitle !== undefined ? data.mediaTitle : existing.mediaTitle,
                         lastSeen: Date.now()
                     });
 

shared/constants.js

@@ -3,7 +3,7 @@
  */
 
 export const PROTOCOL_VERSION = "1.0.0";
-export const APP_VERSION = "1.0.0";
+export const APP_VERSION = "1.0.3";
 
 export const OFFICIAL_SERVER_URL = 'wss://sync.shik3i.net';
 export const OFFICIAL_LANDING_PAGE_URL = 'https://koalasync.shik3i.net';