UI: Overwrite website logo/favicon with new monochrome icon

UI: Update KoalaSync icon to monochrome version to match neon theme
UI: Add new icon to popup header next to title
2026-07-26 12:08:15 +00:00 · 2026-05-18 14:58:18 +02:00 · 2026-05-18 14:56:22 +02:00 · 2026-05-18 14:52:06 +02:00 · 2026-05-16 13:08:53 +02:00 · 2026-05-04 05:55:46 +02:00
47 changed files with 3401 additions and 479 deletions
@@ -7,7 +7,5 @@ extension/
 website/
 scripts/
 *.md
-*.bat
-*.sh
 .env
 server/.env
@@ -52,19 +52,40 @@ jobs:
      - name: Checkout code
        uses: actions/checkout@v4

-      - name: Sync Protocol Constants
-        run: |
-          chmod +x ./scripts/sync-constants.sh
-          ./scripts/sync-constants.sh
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT

-      - name: Create Extension Zip
+      - name: Inject version into source files
        run: |
-          zip -r koala-sync-extension.zip extension/ -x "*.DS_Store*"
+          VERSION=${{ steps.version.outputs.VERSION }}
+          echo "Injecting version $VERSION from tag $GITHUB_REF_NAME..."
+
+          # 1. extension/manifest.base.json
+          jq --arg v "$VERSION" '.version = $v' extension/manifest.base.json > tmp.json && mv tmp.json extension/manifest.base.json
+          echo "  ✓ manifest.base.json -> $VERSION"
+
+          # 2. shared/constants.js — APP_VERSION
+          sed -i "s/export const APP_VERSION = '.*'/export const APP_VERSION = '$VERSION'/" shared/constants.js
+          echo "  ✓ shared/constants.js -> $VERSION"
+
+          # 3. package.json
+          jq --arg v "$VERSION" '.version = $v' package.json > tmp.json && mv tmp.json package.json
+          echo "  ✓ package.json -> $VERSION"
+
+          echo "Version injection complete."
+
+      - name: Build Extensions
+        run: |
+          npm install
+          npm run build:extension

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
-          files: koala-sync-extension.zip
+          files: |
+            dist/koalasync-chrome.zip
+            dist/koalasync-firefox.zip
          name: Release ${{ github.ref_name }}
          generate_release_notes: true
          draft: false
@@ -38,8 +38,7 @@ 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/README.md
+extension/shared/

 # Temporary scratch files
 scratch/
@@ -15,31 +15,41 @@ KoalaSync is a specialized tool for **synchronized video playback** across multi
 - **Identity**: Users are identified by a unique hex `peerId` combined with a customizable `username`.

 ## 2. Repository Structure
- `extension/`: Chrome Extension (Manifest V3). Contains background service worker, content scripts, and popup UI.
+- `extension/`: Browser Extension (Chrome & Firefox, Manifest V3). Contains background service worker, content scripts, and popup UI.
 - `server/`: Node.js Relay Server using Socket.IO (WebSocket-only).
 - `website/`: **Landing Page** & Invitation Bridge (Marketing, Tutorials, and Downloads).
 - `shared/`: **Single Source of Truth** for protocol constants and event names.
- `scripts/`: Utility scripts (e.g., `sync-constants.sh`).
+- `scripts/`: Development utilities (e.g., `build-extension.js`).
 - `docker-compose.yml`: Root-level orchestration for the relay server.

 > [!IMPORTANT]
-> **Single Source of Truth**: `shared/constants.js` and `shared/blacklist.js` are the master files. They must be synchronized to the `extension/shared/` directory using `.\scripts\sync-constants.bat` or `./scripts/sync-constants.sh`. 
+> **Single Source of Truth**: `shared/constants.js` and `shared/blacklist.js` are the master files. They must be synchronized to the `extension/shared/` directory using `node scripts/build-extension.js`. 
 > - **Extension Modules** (`background.js`, `popup.js`) import directly from `./shared/constants.js`.
-> - **Content Scripts** (`content.js`) use a **manual synchronous mirror** to prevent race conditions during page load. Always verify parity after sync.
+> - **Content Scripts** (`content.js`) use a **marker-injected synchronous copy** of the constants. The build script automatically replaces the marked blocks — no manual mirroring needed.

 ## 3. Mandatory Reading
 Before touching any code, you MUST read the following documents in order:
-1. [ARCHITECTURE.md](ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol.
+1. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol.
 2. [extension/README.md](extension/README.md) – Extension components, tab structure, and loading process.
-3. [SYNC_GUIDE.md](SYNC_GUIDE.md) – Protocol constants and synchronization requirements.
+3. [docs/SYNC_GUIDE.md](docs/SYNC_GUIDE.md) – Protocol constants and synchronization requirements.

 ## 4. The "Vanilla JS Mirror" Pattern
 To avoid boot-time race conditions in Manifest V3 without a bundler, the following architectural trade-off is enforced:
 - **Synchronous Execution**: `content.js` MUST execute synchronously to catch early media events. 
- **Manual Mirroring**: `content.js` maintains a manual mirror of the `EVENTS` constants from `shared/constants.js`.
- **Maintenance**: Developers must ensure that any changes to `shared/constants.js` are manually reflected in `content.js` after running the sync scripts.
+- **Automated Injection**: The build script (`node scripts/build-extension.js`) automatically injects `EVENTS` and `HEARTBEAT_INTERVAL` into `content.js` using marker-based replacement (see `scripts/README.md` for marker details).
+- **Maintenance**: After modifying `shared/constants.js`, simply run the build script. No manual mirroring is required.

-## 5. Design Guidelines
+## 5. File Responsibility Map
+
+| File | Responsibility |
+|:-----|:---------------|
+| `background.js` | WebSocket client, state orchestrator, event router, session persistence |
+| `content.js` | Video element detection, media control, event origin detection (loop prevention) |
+| `popup.js` | UI rendering, user input handling, peer display, invitation link generation |
+| `bridge.js` | Landing page ↔ extension communication for invitation join flow |
+| `server/index.js` | Room management, message relay, rate limiting, authentication, peer lifecycle |
+
+## 6. Design Guidelines
 The popup UI follows a strict design system. Do not modify these variables or the layout structure without explicit approval.
 - **Font**: System font stack. **MANDATORY**: No external CDNs or Google Fonts to ensure 100% privacy.
 - **Popup Width**: Fixed at `320px`.
@@ -53,9 +63,10 @@ The popup UI follows a strict design system. Do not modify these variables or th
  | `--success` | `#22c55e` | Success states / Online dot |
  | `--error` | `#ef4444` | Errors / Offline dot |

-## 5. Non-Negotiables (Core Logic)
+## 7. Non-Negotiables (Core Logic)
 The following features are critical and must not be removed or fundamentally altered:
 - **Two-Phase Force Sync**: The `Prepare` → `ACK` → `Execute` flow ensures all peers are buffered before playback resumes.
+- **Episode Auto-Sync**: Ensures series binges stay perfectly synced. A lobby initiates during title transitions, freezing peers until everyone is ready.
 - **Dual Heartbeat**: 
    - **Background Heartbeat (30s)**: Ensures session persistence even without a video element.
    - **Content Heartbeat (15s)**: Transmits current video metadata (time, title).
@@ -66,33 +77,44 @@ The following features are critical and must not be removed or fundamentally alt
 - **SW Keep-alive**: Use of `chrome.alarms` to prevent the Manifest V3 Service Worker from suspending.
 - **Diagnostics**: The "Dev" tab provides real-time access to the underlying `<video>` state for troubleshooting.
 - **Persistence**: `peerId` and `username` must be stored to remain stable across sessions.
+- **Room ID Format**: Room IDs are restricted to `[a-zA-Z0-9-]` only (alphanumeric + hyphens). This is enforced server-side.

-## 6. Technical Constraints
+## 8. Technical Constraints
 - **No Bundler**: The extension uses plain ES Modules. Do not introduce build steps or npm packages into the `extension/` folder.
- **Manual Protocol**: `background.js` implements a subset of the Socket.IO wire protocol natives.
+- **Manual Protocol**: `background.js` implements a subset of the Socket.IO wire protocol natively.
 - **Server Transport**: Restricted to `websocket` only. Polling is disabled.
 - **Docker Context**: The Docker build must run from the **Repo Root**.
 - **Manifest Settings**: `run_at` must remain `document_idle`, and `all_frames` must remain `false`.

-## 7. Security & Deployment
+## 9. Security & Deployment
 - **Tokens**: Security tokens are intentionally managed via `shared/constants.js` and server `.env`.
 - **Environment**: `.env` is excluded via `.gitignore`. Only `.env.example` should be committed.
 - **Revocation**: `MIN_VERSION` check on the server is used to deprecate old extension versions.
 - **Invitation Links**: Correctly propagate server URLs, Room IDs, and Passwords via the URL hash to the bridge.

-## 8. Common Workflows
+## 10. Common Workflows
+
+### Releasing a New Version (CRITICAL WORKFLOW FOR AI AGENTS)
+> [!CAUTION]
+> **AI AGENTS MUST FOLLOW THIS EXACT SEQUENCE WHEN RELEASING A NEW VERSION OR TAGGING.**
+> The CI pipeline automatically injects the version from the git tag into `manifest.base.json`, `shared/constants.js`, and `package.json`. You do NOT need to manually bump version numbers.
+1. Commit all code changes and push to `main`.
+2. Create and push a new tag. **MANDATORY**: Tags MUST start with a `v` (e.g., `v1.4.0`). The GitHub Actions release workflow is strictly configured to ignore any tags without the `v` prefix.
+3. The CI will extract the version from the tag (e.g., `v1.4.0` → `1.4.0`), inject it into all source files, build the extension artifacts, publish the Docker image, and create a GitHub Release.
+4. Verify the release builds on GitHub Actions.

 ### Adding a Protocol Event
 1. Add the event name to `shared/constants.js`.
-2. Run the sync script (`.\scripts\sync-constants.bat` or `./scripts/sync-constants.sh`).
+2. Run the build script (`node scripts/build-extension.js`).
 3. Implement the handler in `server/index.js` and `background.js`.

 ### Testing Locally
-1. Load `extension/` as an "Unpacked Extension" in Chrome.
-2. Start the server from the root: `docker-compose up --build`.
-3. Use **different browser profiles** or vendors to test multi-peer logic.
-4. Use the **Dev tab** to verify real-time video element metadata.
+1. Run the build script: `node scripts/build-extension.js`.
+2. Load `dist/chrome/` as an "Unpacked Extension" in Chrome (or `dist/firefox/` in Firefox).
+3. Start the server from the root: `docker-compose up --build`.
+4. Use **different browser profiles** or vendors to test multi-peer logic.
+5. Use the **Dev tab** to verify real-time video element metadata.

 ### Locking Old Versions
-1. Increase `APP_VERSION` in `shared/constants.js`.
-2. Update `MIN_VERSION` in the server's `.env` file and restart.
+1. Update `MIN_VERSION` in the server's `.env` file to the minimum acceptable version.
+2. Restart the server. Older extensions will be rejected with a "Version too old" error.
@@ -0,0 +1,58 @@
+# Contributing to KoalaSync
+
+Thank you for your interest in contributing to KoalaSync! We welcome all contributions, from bug reports to new features.
+
+## Development Workflow
+
+### 1. Prerequisites
+- Node.js (v18+)
+- Docker (for local server testing)
+
+### 2. Setup
+1. Clone the repository.
+2. Run `npm install` in the root directory to install build dependencies.
+3. Run the build script to synchronize protocol constants and generate browser bundles:
+   ```bash
+   node scripts/build-extension.js
+   ```
+
+### 3. Testing Locally
+1. Load `dist/chrome/` as an "Unpacked Extension" in Chrome (`chrome://extensions/` → Developer Mode → Load Unpacked).
+2. For Firefox, load `dist/firefox/` via `about:debugging` → "Load Temporary Add-on".
+3. Start the relay server: `docker-compose up --build`.
+4. Use **two different browser profiles** (or Chrome + Firefox) to test multi-peer synchronization.
+5. Use the extension's **Dev tab** to verify real-time video element metadata (`readyState`, `currentTime`, `paused`).
+
+### 4. Protocol Synchronization
+KoalaSync uses a "Single Source of Truth" for protocol constants in `shared/constants.js`. 
+- **CRITICAL**: If you modify the constants, you MUST run the build script:
+  ```bash
+  node scripts/build-extension.js
+  ```
+  This will automatically synchronize the changes to the extension and generate the browser-specific bundles in the `dist/` folder.
+
+### 5. Code Standards
+- **Vanilla JS**: The extension must remain dependency-free. Do not add npm packages to the `extension/` directory.
+- **Privacy**: Do not add external requests (CDNs, fonts, analytics, etc.).
+- **Comments**: Maintain the existing documentation style, especially for complex sync logic.
+- **Room IDs**: Room IDs are restricted to `[a-zA-Z0-9-]` (alphanumeric + hyphens only). Ensure any UI that generates room IDs follows this constraint.
+
+### 6. Version Numbers
+> [!IMPORTANT]
+> **Do NOT manually bump version numbers.** The CI pipeline automatically injects the version from the git tag into `manifest.base.json`, `shared/constants.js`, and `package.json` during release builds. Manually changing version numbers in a PR will cause conflicts.
+
+## Pull Request Process
+1. Create a new branch for your feature or bugfix.
+2. Ensure your code is tested locally (Chrome and Firefox).
+3. Update relevant documentation (e.g., `docs/ARCHITECTURE.md` if you change the protocol).
+4. Submit your PR with a clear description of the changes.
+
+## Bug Reports
+When reporting a bug, please include:
+- **Browser**: Chrome / Firefox / Edge + version number.
+- **Extension Version**: Visible in the popup's Dev tab.
+- **Dev Tab Output**: Copy the connection status, logs, and video debug info from the Dev tab.
+- **Steps to Reproduce**: A clear sequence of actions that triggers the issue.
+
+## Security
+If you find a security vulnerability, please do not open a public issue. Instead, refer to our [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
@@ -0,0 +1,37 @@
+# KoalaSync - Production Caddy Configuration Example
+# Replace domains and paths with your actual setup.
+
+# 1. Marketing Website & Invitation Bridge
+sync.koalastuff.net {
+    root * /var/www/koalasync/website
+    file_server
+    encode zstd gzip
+
+    # Security Headers
+    header {
+        # Prevent FLoC tracking
+        Permissions-Policy interest-cohort=()
+        # Security best practices
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        X-Content-Type-Options nosniff
+        X-Frame-Options DENY
+        Referrer-Policy no-referrer-when-downgrade
+    }
+}
+
+# 2. Relay Server (Socket.IO / WebSocket)
+syncserver.koalastuff.net {
+    reverse_proxy localhost:3000 {
+        # Ensure WebSocket support is explicitly handled if needed
+        # (Caddy usually handles this automatically)
+        header_up Host {host}
+        header_up X-Real-IP {remote_host}
+    }
+
+    # Security Headers for the relay
+    header {
+        X-Content-Type-Options nosniff
+        X-Frame-Options DENY
+        Referrer-Policy no-referrer
+    }
+}
@@ -0,0 +1,50 @@
+# Privacy Policy
+
+**KoalaSync does not collect, store, or sell any personal data.**
+
+KoalaSync is designed with a **Security-First & Volatile** architecture. This means we prioritize keeping your data out of persistent storage, though certain technical data must be processed temporarily to ensure service stability and security.
+
+## 1. Data Processing (In-Memory Only)
+KoalaSync does not use a database. All active session data exists only in the server's RAM and is purged immediately when no longer needed.
+- **Session Data**: To synchronize playback, the server must temporarily hold your `peerId`, `username`, and the `title` of the video you are watching. Additionally, playback metadata (`mediaTitle`, `playbackState`, `currentTime`, `volume`, `muted`) is held per peer for the duration of the session. All of this is deleted as soon as you leave the room.
+- **Room Passwords**: If you set a room password, it is stored only as a secure **bcrypt hash** in RAM. The server never sees or stores your plaintext password.
+- **Routing Maps**: The server maintains ephemeral lookup tables (`socketToRoom`, `peerToSocket`) to route messages between peers. These contain only transport identifiers and are purged on disconnect.
+
+### Data Retention
+| Data Type | Maximum Retention | Trigger for Deletion |
+|:----------|:------------------|:---------------------|
+| Session data (peerId, username, video metadata) | Duration of session | User leaves room or disconnects |
+| Room state | 2 hours max | Last peer leaves, or inactivity timeout |
+| Failed auth lockout records | 15 minutes | Automatic expiry |
+| Auth failure records | 1 hour | Periodic cleanup |
+| Connection rate-limit counters | 60 seconds | Automatic expiry |
+| Event rate-limit counters | 10 seconds | Automatic expiry + periodic cleanup |
+
+## 2. Security & Rate Limiting
+To prevent abuse and brute-force attacks, the following data is processed:
+- **Brute-Force Protection**: If multiple failed password attempts are detected, the server stores the `IP address` and `Room ID` in a temporary RAM-based lockout list for a maximum of 15 minutes.
+- **Connection Rate Limiting**: IP addresses are tracked for 60 seconds to prevent connection-flooding (DoS) attacks.
+- **Event Rate Limiting**: Per-socket event counters are tracked for 10-second windows to prevent event-spamming. These are keyed by ephemeral socket IDs and cleaned up periodically.
+- **Console Logging**: The official relay server (`syncserver.koalastuff.net`) outputs connection events (including IP addresses) to the server console for real-time monitoring. These logs are ephemeral and are not archived, sold, or linked to any persistent user identity.
+
+## 3. Extension Permissions
+The browser extension requires the following permissions:
+- `storage`: To remember your local preferences (username, server URL, room settings).
+- `tabs` & `scripting`: To detect and control video elements on the pages you choose to sync.
+- `<all_urls>` (host permission): Required to detect `<video>` elements on any website the user chooses to synchronize. The extension only activates on the specific tab the user has actively selected — it does not scan, monitor, or interact with any other tabs or pages.
+- `alarms`: To keep the background service worker alive during active sync sessions.
+- `notifications`: To display sync status updates (e.g., "Peer joined", "Force Sync initiated").
+- **No History Access**: We do not read, store, or transmit your browsing history. We only interact with the specific tab you have actively selected for synchronization.
+
+## 4. Zero Third-Party Requests
+KoalaSync is completely self-contained:
+- **No CDNs or External Libraries**: All scripts and styles are self-hosted.
+- **No Analytics**: We do not use Google Analytics, tracking pixels, or any third-party telemetry.
+- **No External Fonts**: We use system font stacks to prevent tracking via font services.
+
+## 5. Self-Hosted Instances
+This privacy policy applies to the **official KoalaSync relay server** at `syncserver.koalastuff.net`. If you choose to self-host a relay server using our open-source Docker image, the data handling practices of that instance are the responsibility of the server operator.
+
+---
+
+**Auditable & Open Source**: Because KoalaSync is open source, you can verify these claims by reviewing the [Server Source Code](https://github.com/Shik3i/KoalaSync/blob/main/server/index.js) and the [Extension Logic](https://github.com/Shik3i/KoalaSync/blob/main/extension/content.js).
@@ -1,69 +1,89 @@
 # KoalaSync

-KoalaSync is a premium, lightweight Chrome Extension and Relay Server for synchronized video playback across any website (YouTube, Twitch, Netflix, and custom HTML5 players).
+<p align="center">
+  <a href="https://github.com/Shik3i/KoalaSync/actions/workflows/release.yml"><img src="https://github.com/Shik3i/KoalaSync/actions/workflows/release.yml/badge.svg" alt="Release Status"></a>
+  <a href="https://github.com/Shik3i/KoalaSync/releases"><img src="https://img.shields.io/github/v/release/Shik3i/KoalaSync" alt="GitHub release"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/Shik3i/KoalaSync?color=blue" alt="License"></a>
+  <img src="https://img.shields.io/badge/Browser-Chrome%20|%20Firefox-blueviolet" alt="Cross Browser">
+</p>

-> [!TIP]
-> **New Developers & AI Agents**: Please read [AI_INIT.md](AI_INIT.md) before starting work.
+KoalaSync is a premium, lightweight Browser Extension and Relay Server for synchronized video playback across any website—YouTube, Twitch, Netflix, and custom HTML5 players. Built with a focus on **Data Sovereignty** and **Extreme Performance**.

-## Repository Structure
- `extension/`: Chrome Extension (Manifest V3, Vanilla JS).
- `server/`: Node.js + Socket.IO Relay Server (Containerized).
- `website/`: Marketing landing page & **Invitation Bridge**.
- `shared/`: Protocol constants and domain blacklist.
- `scripts/`: Development utilities for protocol synchronization.
+### 🌟 Why KoalaSync?

-> [!NOTE]
-> For deep technical dives, see [ARCHITECTURE.md](ARCHITECTURE.md) and [SYNC_GUIDE.md](SYNC_GUIDE.md).
+*   **🛡️ Security-First**: Volatile RAM-based relay with built-in brute-force protection and zero-persistence architecture.
+*   **📡 Direct Logic**: Custom wire protocol implementation for frame-perfect synchronization.
+*   **🛠️ Clean Build**: Dependency-free extension runtime with no library overhead.
+*   **🌐 Universal**: Works on any website with a `<video>` tag.
+
+---
+
+### ✨ Key Features

-## 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.
+- **Episode Auto-Sync**: Perfectly sync series binges. All peers wait until everyone has loaded the next episode before starting together.
+- **Smart Matching**: Automatically highlights tabs containing matching video titles.
 - **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.
- **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.
+- **Zero-Latency Relay**: Custom wire protocol implementation for maximum performance.
+- **Seamless Invitations**: Smart links that automatically configure server and room credentials for your friends.

-## Setup Instructions
+---

-### 1. Relay Server (Docker)
-The server runs on Node.js using Socket.IO, containerized for easy deployment.
+### 📂 Repository Structure

+- `extension/`: Browser Extension (Chrome & Firefox).
+- `server/`: Node.js + Socket.IO Relay Server (Containerized).
+- `website/`: Marketing landing page & Invitation Bridge.
+- `shared/`: **Single Source of Truth** for protocol constants.
+- `scripts/`: Automated build and synchronization utilities.
+- `docs/`: Technical deep-dives ([Architecture](docs/ARCHITECTURE.md), [Sync Guide](docs/SYNC_GUIDE.md)).
+
+---
+
+### 🚀 Quick Start
+
+#### For Users (Installation)
+The easiest way to install KoalaSync is to download the pre-compiled version from the [Releases](https://github.com/Shik3i/KoalaSync/releases) page.
+1. Download the latest `koalasync-chrome.zip` or `koalasync-firefox.zip`.
+2. Extract the file and load it as an "Unpacked Extension" in your browser's Developer Mode.
+
+#### For Developers (Building)
+To build the extension from source and synchronize protocol constants:
 ```bash
-# From the root directory
-docker-compose up -d --build
+npm install
+node scripts/build-extension.js
 ```
-The server will be available at `ws://localhost:3000`.
+The compiled artifacts will be available in the `dist/` directory.

-### 2. Chrome Extension
-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.
+#### For Self-Hosting (Docker)
+Deploy your own private relay server using our official image:
+```bash
+# Pull the latest image
+docker pull ghcr.io/shik3i/koalasync:latest

-## Usage
-1. Open the extension and go to the **Settings** tab to set your **Username**.
-2. Go to the **Room** tab, enter your Server URL (default: `ws://localhost:3000`), and click **Join / Create Room**.
-3. In the **Sync** tab, select the tab containing the video you want to sync.
-4. Share the **Invite Link** from the Room tab. When your friends click it, they will automatically join your room and server.
-5. Use **Force Sync** to perfectly align everyone to your current timestamp.
+# Or use our example compose file
+cp docker-compose.example.yml docker-compose.yml
+docker-compose up -d
+```
+The server will be available at `ws://localhost:3000`. See [docker-compose.example.yml](docker-compose.example.yml) for advanced configuration.

-## Technical Details
- **Manifest V3**: Uses a persistent Service Worker with Alarm-based keep-alive.
- **Manual Socket.IO Protocol**: The extension implements the Socket.IO v4 wire protocol natively for extreme performance and zero dependencies.
- **Dead Peer Pruning**: The server automatically prunes peers after 5 minutes of total inactivity (detected via dual heartbeats).
- **Two-Phase Sync**: Ensures all peers are buffered (`readyState >= 3`) before resuming playback.
+To connect your extension to a self-hosted server, open the popup → **Room** tab → select **Custom Server** → enter your server's WebSocket URL (e.g., `ws://localhost:3000`).

-## Security & Privacy
-> [!IMPORTANT]
-> **Privacy First**: KoalaSync stores no data on disk. All room states exist only in RAM and are purged immediately when empty. There is zero telemetry, tracking, or analytics.
+> **⚠️ Note**: `ws://` only works for `localhost`. If you deploy to a real domain, you **must** use `wss://` (e.g., `wss://sync.yourdomain.com`). This requires a TLS-terminating reverse proxy (e.g., Caddy, Nginx, or Traefik) in front of the relay server. See [Caddyfile.example](Caddyfile.example) for a production-ready template.

-## Troubleshooting
- **Logs**: Check the **Dev** tab in the extension popup for live connection logs and video state diagnostics.
- **Handshake**: Verify you see `Joined Namespace /` in the logs.
- **Permissions**: Ensure the target site hasn't blocked script injection (rare for most video sites).
+---
+
+### 📖 Documentation & Links
+
+- **[PRIVACY.md](PRIVACY.md)**: Data Handling and Privacy Policy.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)**: How to help make KoalaSync better.
+- **[HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)**: Step-by-step walkthrough of the complete user flow.
+- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Deep-dive into the two-phase sync and heartbeat logic.
+- **[SECURITY.md](SECURITY.md)**: Disclosure policy and security practices.
+- **[Caddyfile.example](Caddyfile.example)**: Production Caddy configuration for website and relay.
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/Shik3i">Shik3i</a>. KoalaSync is Open Source under the <a href="LICENSE">MIT License</a>.</sub>
+</div>
@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Versions
+
+We take the security of our users and their data very seriously. We actively support and patch the latest stable releases of KoalaSync. 
+
+| Version        | Supported          |
+| -------------- | ------------------ |
+| Latest Release | :white_check_mark: |
+| Older Versions | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability within KoalaSync (e.g., related to the Node.js relay server, WebSocket wire protocol, or the Chrome/Firefox browser extension), please **DO NOT** report it by creating a public GitHub issue. 
+
+Publicly disclosing a vulnerability before a patch is available puts our users at risk. Instead, please send an email privately to the project administrator at:
+**koalasync_admin@koalamail.rocks**
+
+### What to expect
+1. **Acknowledgment**: You should receive an acknowledgment of your report within 48 hours.
+2. **Investigation**: We will investigate the issue, confirm its severity, and work on a patch.
+3. **Resolution**: We will notify you when the patch is deployed to the Chrome Web Store, Mozilla Add-on Store, and our GitHub Docker releases.
+4. **Disclosure**: Once the fix is confirmed and users have had time to update, we will publicly acknowledge your contribution in our release notes (unless you prefer to remain anonymous).
@@ -1,43 +0,0 @@
-# KoalaSync Protocol Synchronization Guide
-
-## Why do we need to sync?
-KoalaSync uses a "Single Source of Truth" for its communication protocol constants located in the root `shared/` directory. However, Chrome Extensions (Manifest V3) are strictly sandboxed and **cannot load or import files from outside their root directory**.
-
-To ensure that the extension and the relay server are always using the exact same event names and protocol versions, we maintain a mirrored copy of the shared files within the `extension/shared/` folder.
-
-## When should you run the sync script?
-You MUST run the synchronization script in any of the following scenarios:
-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
-
-### On Windows
-Run the batch script from the repository root:
-```powershell
-.\scripts\sync-constants.bat
-```
-
-### On macOS / Linux
-Run the shell script from the repository root:
-```bash
-./scripts/sync-constants.sh
-```
-
-## What does it do?
-The script performs the following actions:
-1. Ensures the `extension/shared/` directory exists.
-2. Copies `shared/constants.js` to `extension/shared/constants.js`.
-3. Copies `shared/blacklist.js` to `extension/shared/blacklist.js`.
-
-## Protocol Versioning
-As of v1.0.0-RC5, the system enforces a strict `protocolVersion` check during the `JOIN_ROOM` handshake. 
- The version is defined in `shared/constants.js`.
- If the extension and server versions mismatch, the server will reject the connection with an `Incompatible protocol version` error.
- **Always run the sync script** after bumping the version number to ensure both components are updated.
-
-> [!CAUTION]
-> **NEVER** edit the files inside `extension/shared/` directly. They will be overwritten the next time the sync script is run. Always edit the files in the root `shared/` directory and then run the sync script.
@@ -0,0 +1,25 @@
+services:
+  koala-sync:
+    image: ghcr.io/shik3i/koalasync:latest
+    container_name: KoalaSync
+    restart: always
+    ports:
+      - "3000:3000"
+    environment:
+      - TZ=Europe/Berlin
+      - PORT=3000
+      - MIN_VERSION=1.0.0
+      - MAX_ROOMS=100
+      - MAX_PEERS_PER_ROOM=50
+    # KoalaSync uses in-memory storage for the relay, 
+    # so no persistent database volume is required.
+    pids_limit: 2048
+    # Example for custom network (e.g., Unraid/Macvlan)
+    # networks:
+    #   custom_network:
+    #     ipv4_address: 192.168.1.XXX
+
+# networks:
+#   custom_network:
+#     external: true
+#     name: br0
@@ -1,4 +1,3 @@
-version: '3.8'

 services:
  server:
@@ -16,7 +16,7 @@ This document describes the communication flows and internal logic of the KoalaS
 ## 2. Media Event Synchronization
 When a user interacts with a video:
 1. **Detection**: `content.js` listens to native events (`play`, `pause`, `seeked`) on the `<video>` element.
-2. **Prevention of Loops**: Uses `lastTargetState` to distinguish between user actions and programmatic actions triggered by the extension.
+2. **Prevention of Loops**: Uses an `expectedEvents` Set to distinguish between user actions and programmatic actions. Expected events are consumed on match and expire via timeout.
 3. **Reporting**: `content.js` sends a `CONTENT_EVENT` to `background.js`.
 4. **Relay**: The Server forwards the event to all other peers in the room.
 5. **Execution**: Remote peers receive the command and call `video.play()`, `video.pause()`, or `video.currentTime = targetTime`.
@@ -24,26 +24,44 @@ When a user interacts with a video:
 ## 3. Two-Phase Force Sync
 Ensures all peers are frame-perfect and buffered before resuming:
 1. **Prepare**: Initiator sends `FORCE_SYNC_PREPARE` with the target timestamp.
-2. **Buffer**: Peers seek and pause. Once buffered (`readyState >= 3`), they send a `FORCE_SYNC_ACK`.
-3. **Execute**: Once the Initiator collects ACKs (or after a 5s timeout), they send `FORCE_SYNC_EXECUTE`.
+2. **Buffer**: Peers seek and pause. Once buffered (`readyState >= 3`), they send a `FORCE_SYNC_ACK`. (Note: `content.js` limits polling to 8000ms).
+3. **Execute**: Once the Initiator collects ACKs (or after an 8.5s timeout), they send `FORCE_SYNC_EXECUTE`.
+   > [!IMPORTANT]
+   > **Network Transit Buffer Rule**: The orchestrator (`background.js`) must always use a timeout at least 500ms longer than the worker (`content.js`) to account for IPC and network transit time. Never align them exactly 1:1, as this will introduce a race condition on slow connections.
 4. **Resume**: All peers call `play()` simultaneously.

-## 4. Peer Lifecycle & Dual Heartbeat
+## 4. Episode Auto-Sync
+Maintains continuous synchronized viewing when watching series:
+1. **Detection**: `content.js` monitors the Media Session API for title changes.
+2. **Lobby Creation**: When a new title is detected, the peer initiates an `EPISODE_LOBBY` and broadcasts the new title.
+3. **Wait State**: All peers freeze their video until they have also loaded the exact same title.
+4. **Mid-Lobby Joins**: If a new user joins the room during an active lobby, the lobby initiator broadcasts the active lobby state so the newcomer can sync up.
+5. **Resume**: Once all peers report `EPISODE_READY`, the lobby is resolved and playback resumes perfectly.
+
+## 5. Peer Lifecycle & Dual Heartbeat
 To maintain a clean room state and eliminate "Ghost Peers":
 - **Session Heartbeat (Background)**: Every 30 seconds, `background.js` sends an "I'm alive" signal to the server. This keeps you in the room even if no video is playing.
 - **Video Heartbeat (Content)**: Every 15 seconds, `content.js` sends current playback metadata (time, title, state) if a video is found.
 - **Server Pruning**: The server runs a "Reaper" every 2 minutes. If a peer has sent **zero** activity (no events and no heartbeats) for 5 minutes, they are forcefully disconnected.
 - **Immediate Cleanup**: Rooms are deleted instantly when the last peer leaves or disconnects.

-## 5. Security & Stability
+> [!CAUTION]
+> **Identity Rule**: Differentiate between `peerId` and `socket.id`. Use `socket.id` exclusively for ephemeral transport routing on the server. Use `peerId` exclusively for identity, state management, and room tracking across the stack.
+
+## 6. Broadcast Protocol & Routing
+KoalaSync uses a megaphone routing approach to minimize server logic:
+- **`emit()` Broadcast Behavior**: Any `emit()` from the extension client is unconditionally broadcast to **all other peers in the room**. It is not a direct message. 
+- **Storm Prevention**: When dispatching state updates in response to a new user joining (e.g., an active lobby state), ensure ONLY the initiator (or a designated leader) calls `emit()` to prevent $O(N)$ broadcast storms.
+
+## 7. Security & Stability
 - **Service Worker Lifecycle**: Uses `chrome.alarms` to prevent the Manifest V3 service worker from suspending while in an active room.
 - **Rate Limiting**: Server-side per-socket and per-IP rate limits to prevent sync-spamming or DoS.
 - **Noise Filtering**: Uses a curated blacklist of domains (Search Engines, Social Media) to declutter the "Target Tab" selector in the popup.
 - **Diagnostics**: A "Dev" tab provides real-time access to the underlying `<video>` state (`readyState`, `paused`, `currentTime`) for easier troubleshooting.

-## 6. Constant Synchronization & Consistency
+## 8. Constant Synchronization & Consistency
 To maintain a "Single Source of Truth" across the server and extension without using a bundler:
 - **Relay Server & Extension Modules**: `background.js` and `popup.js` import constants directly from `shared/constants.js`.
- **Content Scripts**: To ensure zero-latency execution, `content.js` uses a manual mirror of `EVENTS`. 
- **Synchronization**: The `./scripts/sync-constants.sh` script ensures that the `shared/` folder within the `extension/` directory is kept up-to-date with the root `shared/` source.
- **Verification**: Any protocol change requires a manual verification sweep across all three constant locations (Shared, Server, and Content Script Mirror).
+- **Content Scripts**: To ensure zero-latency execution, `content.js` uses a synchronized copy of `EVENTS` and constants.
+- **Automation**: The `node scripts/build-extension.js` script automatically injects these constants into `content.js` during the build process, eliminating the risk of manual mirror mismatch.
+- **Verification**: Any protocol change is automatically propagated across the stack by running the build script.
@@ -0,0 +1,213 @@
+# KoalaSync — How It Works (Step-by-Step)
+
+This guide walks through the complete user flow of KoalaSync, from creating a room to synchronized playback. It is designed for **store reviewers**, **end-users**, and **manual testers** to understand exactly what happens at each step, what data is sent, and where it goes.
+
+---
+
+## Step 1: Installing the Extension
+
+1. Download the extension from the [Releases](https://github.com/Shik3i/KoalaSync/releases) page (or install from the Chrome Web Store / Firefox Add-ons).
+2. The extension adds a small icon to your browser toolbar.
+3. On first install, a unique 8-character **Peer ID** is generated locally and stored in `chrome.storage.local`. This ID is never sent to any external service — it only travels to the relay server when you join a room.
+
+> **What's stored locally**: `peerId` (8-char hex), `username` (customizable), `serverUrl`, `filterNoise` preference. All stored via `chrome.storage.sync` and `chrome.storage.local`.
+
+---
+
+## Step 2: Connecting to the Relay Server
+
+When you open the extension popup, the background service worker connects to the relay server:
+
+1. **WebSocket Handshake**: `background.js` opens a WebSocket to `wss://syncserver.koalastuff.net/socket.io/?EIO=4&transport=websocket`.
+2. **Security Checks** (server-side):
+   - The server checks the client's **IP rate limit** (max 10 connections per 60 seconds).
+   - The server validates the **authentication token** (hardcoded in `shared/constants.js`) to verify this is a legitimate KoalaSync client.
+   - The server checks the **extension version** against `MIN_VERSION` to reject outdated clients.
+3. **Connection Established**: The server responds with an Engine.IO handshake (`0{...}`), followed by a Socket.IO namespace join (`40`). The connection status dot in the popup turns green.
+
+> **Data sent to server**: `token` (authentication), `version` (e.g., `1.3.1`). No personal data is transmitted during connection.
+
+---
+
+## Step 3: Creating a Room
+
+Click **"Create Room"** in the popup's Room tab:
+
+1. The extension generates a random Room ID (e.g., `happy-koala-42`) and a random 6-character password.
+2. Room IDs are restricted to `[a-zA-Z0-9-]` (alphanumeric + hyphens only).
+3. The extension emits a `JOIN_ROOM` event to the server.
+
+> **Data sent in `JOIN_ROOM`**:
+> ```json
+> {
+>   "roomId": "happy-koala-42",
+>   "password": "x7k2m9",
+>   "peerId": "a1b2c3d4",
+>   "username": "MyName",
+>   "tabTitle": "YouTube - My Video",
+>   "protocolVersion": "1.0.0"
+> }
+> ```
+
+4. **Server-side processing**:
+   - All fields are **sanitized**: `roomId` is stripped of invalid characters and clamped to 64 chars; `peerId` clamped to 16 chars; `password` clamped to 128 chars; `username` clamped to 30 chars.
+   - The server **hashes the password** with bcrypt and stores the hash in RAM (the plaintext is never stored).
+   - A new room object is created in memory with the peer's data.
+   - The server responds with `ROOM_DATA` containing the list of peers in the room.
+
+5. **Popup updates**: The Room tab switches to the "Active Room" view, showing your Room ID and an invitation link.
+
+---
+
+## Step 4: Sharing an Invitation Link
+
+Click the **📋 Copy** button next to the invite link:
+
+1. The extension constructs a URL in this format:
+   ```
+   https://sync.koalastuff.net/join.html#join:<roomId>:<password>:<serverFlag>:<encodedServerUrl>
+   ```
+   - `serverFlag`: `0` for official server, `1` for custom server.
+   - `encodedServerUrl`: Only populated if using a custom server.
+   
+2. **Important**: The room credentials are in the **URL hash** (`#`), which means they are **never sent to the web server** — the hash fragment stays entirely in the browser. The landing page server never sees your room ID or password.
+
+3. Send this link to your friend via any messaging app.
+
+---
+
+## Step 5: Your Friend Opens the Invitation Link
+
+When your friend opens the link in their browser:
+
+1. **`join.html` loads** on `sync.koalastuff.net`. The page displays "INVITATION DETECTED" with the Room ID.
+
+2. **Extension detection**: The page checks for `document.documentElement.dataset.koalasyncInstalled`, which is set by `bridge.js` (a content script injected only on `sync.koalastuff.net`).
+
+3. **If the extension IS installed**:
+   - The page shows "Joining room automatically..."
+   - After 500ms, the page dispatches a `KOALASYNC_JOIN_REQUEST` custom DOM event with `{ roomId, password, useCustomServer, serverUrl }`.
+   - `bridge.js` catches this event and forwards it to `background.js` via `chrome.runtime.sendMessage`.
+   - `background.js` stores the credentials in `chrome.storage.sync` and emits `JOIN_ROOM` to the server.
+   - The server validates the password against the stored bcrypt hash.
+   - On success, the server responds with `ROOM_DATA` and broadcasts `PEER_STATUS { status: 'joined' }` to all existing peers.
+   - The join page updates to show "✅ Successfully joined!".
+
+4. **If the extension is NOT installed**:
+   - The page shows download links (Chrome Web Store / GitHub).
+   - The user installs the extension, returns to the link, and the flow continues from step 3.
+
+---
+
+## Step 6: Selecting a Video Tab
+
+Both users now need to select which browser tab contains the video to sync:
+
+1. Open a video on any website (YouTube, Twitch, Netflix, etc.).
+2. In the extension popup → **Sync** tab → use the **"Target Tab"** dropdown.
+3. The dropdown lists all open tabs, filtered to exclude noise (search engines, social media — configurable via Settings).
+4. Tabs with a **matching video title** are highlighted with a ⭐ prefix for easy identification.
+5. Selecting a tab causes `background.js` to set `currentTabId` and inject `content.js` into that tab via `chrome.scripting.executeScript`.
+
+> **What `content.js` does on injection**: Finds the first `<video>` element on the page and attaches event listeners for `play`, `pause`, `seeked`, `timeupdate`, and `volumechange`. It uses an `expectedEvents` Set to distinguish between user actions and programmatic actions (loop prevention).
+
+---
+
+## Step 7: Synchronized Playback
+
+When User A presses **Play** on their video:
+
+1. `content.js` detects the native `play` event on the `<video>` element.
+2. It checks the `expectedEvents` Set — if this event was expected (caused by a remote command), it's consumed silently. If not, it's a **user action**.
+3. For user actions, `content.js` sends `{ type: 'CONTENT_EVENT', action: 'play', payload: { currentTime, ... } }` to `background.js`.
+4. `background.js` adds an `actionTimestamp` and emits the `PLAY` event to the server.
+5. **Server relay**: The server sanitizes all fields (strings clamped, numbers validated, booleans type-checked) and constructs a clean `relayPayload` with `senderId` set to User A's `peerId`. The raw client data is never forwarded directly.
+6. The server broadcasts the sanitized payload to all other peers in the room.
+7. User B's `background.js` receives the `PLAY` event and calls `routeToContent()`, which sends a `SERVER_COMMAND` message to User B's `content.js`.
+8. User B's `content.js` adds `'playing'` to its `expectedEvents` Set (so it won't echo the event back), then calls `video.play()`.
+
+> **The same flow applies to Pause and Seek**, with Seek additionally sending `targetTime` for the time position.
+
+---
+
+## Step 8: Force Sync (Two-Phase Protocol)
+
+If videos drift out of sync, either user can click **"Force Sync"**:
+
+### Phase 1 — Prepare
+1. The initiator's `content.js` captures the current `video.currentTime` as the `targetTime`.
+2. `background.js` emits `FORCE_SYNC_PREPARE` with `{ targetTime }` to all peers.
+3. All peers (including the initiator) **pause** their video and **seek** to `targetTime`.
+4. Each peer's `content.js` polls `video.readyState` until it reaches `≥ 3` (buffered enough to play), with an 8-second timeout.
+5. Once buffered, each peer sends `FORCE_SYNC_ACK` back.
+
+### Phase 2 — Execute
+6. Once all ACKs are received (or after 8.5 seconds), the initiator emits `FORCE_SYNC_EXECUTE`.
+7. All peers call `video.play()` simultaneously, achieving frame-perfect sync.
+
+> **Why two phases?** Without buffering confirmation, peers with slower connections would start playing before they've loaded the target timestamp, causing immediate desync.
+
+---
+
+## Step 9: Heartbeat & Peer Health
+
+While in a room, two heartbeats keep the session alive:
+
+| Heartbeat | Interval | Source | Purpose |
+|:----------|:---------|:-------|:--------|
+| **Background** | 30 seconds | `background.js` | Signals "I'm still connected" even without a video |
+| **Content** | 15 seconds | `content.js` | Sends video metadata: `currentTime`, `mediaTitle`, `playbackState`, `volume`, `muted` |
+
+- **Server Reaper**: Every 2 minutes, the server checks for peers with no activity for 5+ minutes and disconnects them ("dead peer pruning").
+- **Room Cleanup**: Empty rooms are deleted immediately. Inactive rooms are pruned after 2 hours.
+
+---
+
+## Step 10: Leaving a Room
+
+When a user clicks **"Leave"** or closes their browser:
+
+1. `background.js` emits `LEAVE_ROOM` (or the WebSocket `disconnect` fires automatically).
+2. The server calls `removePeerFromRoom()`, which:
+   - Removes the peer from the room's `peers` Set, `peerIds` Map, and `peerData` Map.
+   - Removes the socket from the global `socketToRoom` and `peerToSocket` maps.
+   - Broadcasts `PEER_STATUS { status: 'left' }` to remaining peers.
+   - If the room is now empty, **deletes the room entirely** — no data persists.
+3. The event rate-limit counter for that socket is also cleaned up.
+
+> **After disconnect, zero data about the user remains on the server.** There is no database, no log file, no analytics record. The session existed only in RAM and is now gone.
+
+---
+
+## Episode Auto-Sync Flow
+
+When watching a series and an episode ends:
+
+1. `content.js` monitors the [Media Session API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API) for title changes.
+2. When a new title is detected, the peer broadcasts `EPISODE_LOBBY` with the expected new title.
+3. All peers' videos freeze. The UI shows an "Episode Lobby" card with peer readiness status.
+4. Each peer's `content.js` polls for the new title to appear in the `<video>` element's metadata.
+5. Once a peer detects the matching title, they send `EPISODE_READY`.
+6. When all peers report ready, the lobby resolves and playback resumes simultaneously.
+
+---
+
+## Data Flow Summary
+
+```
+┌─────────────┐     WebSocket      ┌──────────────┐     WebSocket      ┌─────────────┐
+│  Extension  │ ←─────────────────→│  Relay Server │←──────────────────→│  Extension  │
+│  (User A)   │   JOIN_ROOM        │  (RAM only)   │   JOIN_ROOM        │  (User B)   │
+│             │   PLAY/PAUSE/SEEK  │               │   PLAY/PAUSE/SEEK  │             │
+│             │   FORCE_SYNC_*     │  Sanitizes &  │   FORCE_SYNC_*     │             │
+│             │   PEER_STATUS      │  relays only  │   PEER_STATUS      │             │
+│             │   EPISODE_*        │               │   EPISODE_*        │             │
+└──────┬──────┘                    └───────────────┘                    └──────┬──────┘
+       │                                                                      │
+  ┌────┴─────┐                                                          ┌─────┴────┐
+  │ content  │  Listens to <video> events                               │ content  │
+  │   .js    │  Controls playback                                       │   .js    │
+  └──────────┘                                                          └──────────┘
+```
+
+> **The relay server is a pure message forwarder.** It never interprets video content, accesses URLs, or stores session history. All media control happens locally inside each user's browser via the `<video>` DOM API.
@@ -0,0 +1,7 @@
+# Technical Documentation
+
+This directory contains deep-dives into the KoalaSync protocol and architecture.
+
+- [HOW_IT_WORKS.md](HOW_IT_WORKS.md): Step-by-step walkthrough of every user flow, from room creation to synchronized playback. Ideal for store reviewers and manual testers.
+- [ARCHITECTURE.md](ARCHITECTURE.md): Communication flows, Dual Heartbeat, and Sync logic.
+- [SYNC_GUIDE.md](SYNC_GUIDE.md): Protocol constants and sync requirements.
@@ -0,0 +1,37 @@
+# KoalaSync Protocol Synchronization Guide
+
+## Why do we need to sync?
+KoalaSync uses a "Single Source of Truth" for its communication protocol constants located in the root `shared/` directory. However, Browser Extensions (Manifest V3) are strictly sandboxed and **cannot load or import files from outside their root directory**.
+
+To ensure that the extension and the relay server are always using the exact same event names and protocol versions, we maintain a mirrored copy of the shared files within the `extension/shared/` folder.
+
+## When should you run the build script?
+You MUST run the build script in any of the following scenarios:
+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
+
+Run the Node.js build script from the repository root:
+```bash
+node scripts/build-extension.js
+```
+
+## What does it do?
+The build script performs the following actions:
+1. Synchronizes protocol constants by copying `shared/constants.js`, `shared/blacklist.js`, and `shared/README.md` into `extension/shared/`.
+2. Injects `EVENTS` and `HEARTBEAT_INTERVAL` into `content.js` via marker-based replacement.
+3. Compiles browser-specific manifest files.
+4. Packages the final ready-to-publish extension artifacts for Chrome and Firefox into the `dist/` directory.
+
+## Protocol Versioning
+The system enforces a strict `protocolVersion` check during the `JOIN_ROOM` handshake. 
+- The version is defined in `shared/constants.js`.
+- If the extension and server versions mismatch, the server will reject the connection with an `Incompatible protocol version` error.
+- **Always run the build script** after bumping the version number to ensure both components are updated.
+
+> [!CAUTION]
+> **NEVER** edit the files inside `extension/shared/` directly. They will be overwritten the next time the build script is run. Always edit the files in the root `shared/` directory and then run the build script.
@@ -1,6 +1,6 @@
-# KoalaSync Chrome Extension
+# KoalaSync Browser Extension

-A Manifest V3 Chrome Extension for synchronized video playback across any website.
+A Manifest V3 Browser Extension (Chrome & Firefox) for synchronized video playback across any website.

 ## Key Features
 - **Manifest V3**: Optimized Service Worker architecture with session persistence.
@@ -20,14 +20,20 @@ KoalaSync requires `<all_urls>` permission to detect and interact with video ele
 - **No Browsing History**: We do not track or store your browsing history.
 - **State Management**: Sensitive data (Room Passwords) is stored locally using `chrome.storage`.
 - **Zero Telemetry**: No analytics or external tracking scripts.
+- **Zero Runtime Dependencies**: The extension is built with pure Vanilla JS and contains no external libraries or tracking scripts, ensuring maximum performance and privacy.

 ## Installation
-1. **Sync Protocol**: Run `./scripts/sync-constants.sh` (macOS/Linux) or `scripts\sync-constants.bat` (Windows) from the root.
+1. **Prepare Extension**: From the repository root, run:
+   ```bash
+   node scripts/build-extension.js
+   ```
 2. Open Chrome and go to `chrome://extensions/`.
 3. Enable **Developer mode** (top right).
-4. Click **Load unpacked** and select the `extension` folder.
+4. Click **Load unpacked** and select the `dist/chrome` folder.

 ## Development
-If you modify `shared/constants.js`, you must synchronize the changes across the extension and server:
- **Windows**: Run `scripts\sync-constants.bat`
- **Linux/macOS**: Run `scripts/sync-constants.sh`
+If you modify `shared/constants.js`, you must synchronize the changes by running the build script from the root:
+```bash
+node scripts/build-extension.js
+```
+This ensures that the `extension/shared` folder is updated with the latest protocol constants.
@@ -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,13 +29,14 @@ function ensureState() {
            chrome.storage.session.get([
                'logs', 'history', 'currentRoom', 'lastActionState', 
                'eventQueue', 'isForceSyncInitiator', 'forceSyncAcks', 
-                'forceSyncDeadline', 'reconnectFailed', 'reconnectStartTime', 'currentTabId', 'currentTabTitle'
+                '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);
+                if (data.logs) logs = [...logs, ...data.logs].slice(0, 200);
                if (data.history) history = [...history, ...data.history].slice(0, 20);
                if (data.currentRoom) currentRoom = data.currentRoom;
                if (data.lastActionState) lastActionState = data.lastActionState;
@@ -67,11 +67,22 @@ 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
                if (pendingLogs.length > 0) {
-                    logs = [...pendingLogs, ...logs].slice(0, 50);
+                    logs = [...pendingLogs, ...logs].slice(0, 200);
                    chrome.storage.session.set({ logs });
                    pendingLogs = [];
                }
@@ -100,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() {
@@ -145,7 +169,7 @@ function addLog(message, type = 'info') {
        pendingLogs.unshift(log);
    } else {
        logs.unshift(log);
-        if (logs.length > 50) logs.pop();
+        if (logs.length > 200) logs.pop();
        chrome.storage.session.set({ logs });
    }
    chrome.runtime.sendMessage({ type: 'LOG_UPDATE', log }).catch(() => {});
@@ -418,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(() => {});
@@ -519,19 +539,30 @@ 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,
-                            mediaTitle: data.mediaTitle || null
-                        });
+                        currentRoom.peers.push(createPeerData(data));
                        if (storageInitialized) chrome.storage.session.set({ currentRoom });
                        chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: currentRoom.peers }).catch(() => {});
+
+                        if (episodeLobby && episodeLobby.initiatorPeerId === peerId) {
+                            emit(EVENTS.EPISODE_LOBBY, { peerId, expectedTitle: episodeLobby.expectedTitle });
+                        }
                    }
                } else if (data.status === 'left') {
                    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();
+                    }
+
+                    if (isForceSyncInitiator) {
+                        const peerCount = currentRoom.peers ? currentRoom.peers.length : 1;
+                        if (forceSyncAcks.size >= peerCount) {
+                            executeForceSync();
+                        }
+                    }
                } else {
                    // Heartbeat/Update: Update tabTitle for matching
                    const peer = currentRoom.peers.find(p => (p.peerId || p) === data.peerId);
@@ -540,15 +571,15 @@ function handleServerEvent(event, data) {
                            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,
-                                mediaTitle: data.mediaTitle || null
-                            };
+                            currentRoom.peers[idx] = createPeerData(data);
                        }
                        if (storageInitialized) chrome.storage.session.set({ currentRoom });
                        chrome.runtime.sendMessage({ type: 'PEER_UPDATE', peers: currentRoom.peers }).catch(() => {});
@@ -556,6 +587,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;
@@ -576,6 +652,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() + 8500;
+    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();
+        }
+    }, 8500);
+}
+
+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,
@@ -641,23 +813,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) => {
@@ -703,24 +859,29 @@ 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(() => {});
@@ -793,7 +954,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {
            if (message.action === EVENTS.FORCE_SYNC_PREPARE) {
                isForceSyncInitiator = true;
                forceSyncAcks.clear();
-                const deadline = Date.now() + 5000;
+                const deadline = Date.now() + 8500;
                chrome.storage.session.set({ 
                    isForceSyncInitiator: true, 
                    forceSyncAcks: [], 
@@ -808,7 +969,7 @@ async function handleAsyncMessage(message, sender, sendResponse) {
                        addLog('Force Sync: Timeout waiting for ACKs, executing anyway...', 'warn');
                        executeForceSync();
                    }
-                }, 5000);
+                }, 8500);
            }
            addToHistory(message.action, 'You');
            emit(message.action, { ...message.payload, peerId });
@@ -878,6 +1039,11 @@ async function handleAsyncMessage(message, sender, sendResponse) {
                    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(() => {});
                }
            }
@@ -902,6 +1068,96 @@ async function handleAsyncMessage(message, sender, sendResponse) {
    } 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' });
@@ -1,6 +1,6 @@
 /**
 * KoalaSync Bridge Script
- * Injected into koalasync.shik3i.net to facilitate communication between 
+ * Injected into sync.koalastuff.net to facilitate communication between 
 * the landing page and the extension.
 */

@@ -14,7 +14,8 @@
    }
    window.koalaSyncInjected = true;

-    // Local Protocol Constants (Mirroring shared/constants.js)
+    // --- SHARED_EVENTS_INJECT_START ---
+    // This block is automatically updated by /scripts/build-extension.js
    const EVENTS = {
        PLAY: "play",
        PAUSE: "pause",
@@ -22,12 +23,28 @@
        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"
    };
+    // --- SHARED_EVENTS_INJECT_END ---

    let expectedEvents = new Set();
    let expectedTimeouts = {};

+    // --- Seek Relay Filtering ---
+    // Minimum seek delta (seconds) to report. Prevents HLS/DASH buffering micro-seeks
+    // from being relayed to peers as user-initiated seeks.
+    const MIN_SEEK_DELTA = 3.0;
+    let lastReportedSeekTime = null;  // last currentTime we relayed as a SEEK
+    let seekDebounceTimer = null;     // debounce timer for rapid seek events
+
+    // --- 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]);
@@ -47,6 +64,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();
@@ -181,11 +292,45 @@
                    });
                }
            } 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) {
@@ -211,6 +356,7 @@
                    duration: video.duration || 0,
                    readyState: video.readyState,
                    muted: video.muted,
+                    volume: video.volume,
                    playbackRate: video.playbackRate,
                    url: window.location.href,
                    id: video.id || 'none',
@@ -257,22 +403,75 @@

    const handlePlay = () => reportEvent(EVENTS.PLAY);
    const handlePause = () => reportEvent(EVENTS.PAUSE);
-    const handleSeeked = () => reportEvent(EVENTS.SEEK);
+
+    // Seek filtering: ignore HLS/DASH buffering micro-seeks.
+    // Only relay if delta >= MIN_SEEK_DELTA AND not already debouncing.
+    const handleSeeked = () => {
+        const video = findVideo();
+        if (!video) return;
+        const current = video.currentTime;
+        if (!Number.isFinite(current)) return;
+
+        // Step 1: Check expectedEvents (programmatic seek suppression)
+        if (expectedEvents.has('seek')) {
+            expectedEvents.delete('seek');
+            lastReportedSeekTime = current; // Update baseline so next user seek is relative to here
+            // No log — this is routine programmatic behavior (Force Sync, lobby, peer command)
+            return;
+        }
+
+        const delta = lastReportedSeekTime !== null ? Math.abs(current - lastReportedSeekTime) : null;
+        const deltaStr = delta !== null ? `Δ${delta.toFixed(2)}s` : 'Δ?';
+
+        // Step 2: Delta check — skip micro-seeks (buffering, chapter markers, etc.)
+        if (lastReportedSeekTime !== null && delta < MIN_SEEK_DELTA) {
+            reportLog(`[Seek] Filtered (${deltaStr} < ${MIN_SEEK_DELTA}s threshold) @ ${current.toFixed(2)}s — not relayed`, 'warn');
+            return;
+        }
+
+        // Step 3: Debounce rapid consecutive seeks (e.g. scrubbing)
+        // — wait 800ms for the user to settle before relaying
+        if (seekDebounceTimer) clearTimeout(seekDebounceTimer);
+        seekDebounceTimer = setTimeout(() => {
+            seekDebounceTimer = null;
+            const v = findVideo();
+            if (!v) return;
+            const settled = v.currentTime;
+            const finalDelta = lastReportedSeekTime !== null ? Math.abs(settled - lastReportedSeekTime) : null;
+            const finalDeltaStr = finalDelta !== null ? `Δ${finalDelta.toFixed(2)}s` : 'Δ?';
+            lastReportedSeekTime = settled;
+            reportLog(`[Seek] Relayed @ ${settled.toFixed(2)}s (${finalDeltaStr})`, 'info');
+            reportEvent(EVENTS.SEEK);
+        }, 800);
+    };
+

    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();
+            }
        }
    }

@@ -288,6 +487,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();
        }
    }
@@ -303,6 +506,10 @@
    });
    observer.observe(document.body, { childList: true, subtree: true });

+    // --- SHARED_HEARTBEAT_INJECT_START ---
+    const HEARTBEAT_INTERVAL_VAL = 15000;
+    // --- SHARED_HEARTBEAT_INJECT_END ---
+
    // Heartbeat
    let heartbeatErrorCount = 0;
    const heartbeatInterval = setInterval(() => {
@@ -314,7 +521,9 @@
                payload: {
                    playbackState: video.paused ? 'paused' : 'playing',
                    currentTime: video.currentTime,
-                    mediaTitle: mediaTitle
+                    mediaTitle: mediaTitle,
+                    volume: video.volume,
+                    muted: video.muted
                }
            }).catch(err => {
                if (err.message.includes('Extension context invalidated')) {
@@ -327,9 +536,17 @@
                }
            });
        }
-    }, 15000);
+    }, HEARTBEAT_INTERVAL_VAL);

    // 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);
+        }
+    });
+
 })();
@@ -1,8 +1,8 @@
 {
  "manifest_version": 3,
  "name": "KoalaSync",
-  "version": "1.1.2",
-  "description": "Synchronize video playback across different tabs and users.",
+  "version": "1.3.1",
+  "description": "Watch party extension to synchronize video playback on YouTube, Twitch, Netflix, and HTML5 sites in real-time with friends.",
  "permissions": [
    "storage",
    "tabs",
@@ -22,13 +22,9 @@
      "128": "icons/icon128.png"
    }
  },
-  "background": {
-    "service_worker": "background.js",
-    "type": "module"
-  },
  "content_scripts": [
    {
-      "matches": ["https://koalasync.shik3i.net/*"],
+      "matches": ["https://sync.koalastuff.net/*"],
      "js": ["bridge.js"],
      "run_at": "document_start"
    }
@@ -31,9 +31,19 @@
            font-size: 18px;
            margin: 0 0 16px 0;
            color: var(--accent);
-            text-align: center;
            letter-spacing: 1px;
            text-transform: uppercase;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            gap: 8px;
+        }
+
+        h1 img {
+            width: 24px;
+            height: 24px;
+            object-fit: contain;
+            border-radius: 4px;
        }

        /* Tabs */
@@ -148,9 +158,6 @@
        }

        .peer-item {
-            display: flex;
-            justify-content: space-between;
-            align-items: center;
            padding: 8px 0;
            border-bottom: 1px solid #334155;
        }
@@ -195,7 +202,7 @@
    </style>
 </head>
 <body>
-    <h1>KoalaSync</h1>
+    <h1><img src="icons/icon128.png" alt="KoalaSync Logo">KoalaSync</h1>

    <div class="tabs">
        <button class="tab-btn active" data-tab="tab-room">Room</button>
@@ -290,6 +297,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 +321,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);">
@@ -344,6 +367,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>
@@ -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', '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);
@@ -77,6 +88,9 @@ async function init() {
            
            // 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();
        }
@@ -110,7 +124,7 @@ function updateUI(roomId, password, useCustomServer = false, serverUrl = '') {
        if (elements.activeRoomId) elements.activeRoomId.textContent = roomId;
        if (elements.activeServer) {
            elements.activeServer.textContent = useCustomServer ? (serverUrl || 'Custom Server') : 'Official Server';
-            elements.activeServer.title = useCustomServer ? (serverUrl || '') : 'sync.shik3i.net';
+            elements.activeServer.title = useCustomServer ? (serverUrl || '') : 'syncserver.koalastuff.net';
        }
    } else {
        updatePeerList([]);
@@ -188,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;

@@ -213,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) {
@@ -235,29 +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);

+            // 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;';
+                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);
            }

-            if (pTabTitle) {
-                const titleDiv = document.createElement('div');
-                titleDiv.style.cssText = 'font-size:10px; color:var(--text-muted); opacity: 0.8;';
-                titleDiv.textContent = p.mediaTitle ? `via ${pTabTitle}` : pTabTitle;
-                peerItem.appendChild(titleDiv);
+            // 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);
        });
    };
@@ -536,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 });
 });
@@ -789,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, []);
+            }
+        });
    }
 });

@@ -883,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)`;
+    }
+}
@@ -1,14 +0,0 @@
-# ⚠️ 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.
@@ -0,0 +1,13 @@
+{
+  "name": "koalasync",
+  "version": "1.3.1",
+  "description": "KoalaSync Build Scripts",
+  "private": true,
+  "scripts": {
+    "build:extension": "node scripts/build-extension.js"
+  },
+  "devDependencies": {
+    "archiver": "^7.0.1",
+    "fs-extra": "^11.2.0"
+  }
+}
@@ -0,0 +1,33 @@
+# Development Scripts
+
+This directory contains utility scripts for the KoalaSync development workflow.
+
+## build-extension.js
+
+The primary build tool for KoalaSync. This Node.js script automates two critical tasks:
+
+1.  **Protocol Synchronization**: Copies the "Single Source of Truth" constants (`shared/constants.js`) and the domain blacklist (`shared/blacklist.js`) from the root `/shared` directory into the `extension/shared/` directory.
+2.  **Content Script Injection**: Injects protocol constants directly into `content.js` using marker-based replacement. This is necessary because `content.js` executes synchronously and cannot use ES module imports.
+3.  **Artifact Generation**: Compiles the extension into browser-specific bundles for Chrome and Firefox, located in the `dist/` directory.
+
+### Usage
+
+From the **repository root**, run:
+
+```bash
+node scripts/build-extension.js
+```
+
+### Why this script exists
+KoalaSync uses **Vanilla JS** in the extension to maintain zero runtime dependencies and maximum privacy. Since we don't use a bundler (like Webpack or Vite) inside the extension, this script serves as our lightweight "pre-build" step to ensure that the protocol constants remain synchronized between the extension and the relay server.
+
+### Content Injection Markers
+
+The build script uses marker comments in `content.js` to locate and replace constant blocks:
+
+| Marker Pair | Injected Value | Source |
+|:---|:---|:---|
+| `SHARED_EVENTS_INJECT_START` / `END` | The full `EVENTS` object | `shared/constants.js` |
+| `SHARED_HEARTBEAT_INJECT_START` / `END` | `HEARTBEAT_INTERVAL` value | `shared/constants.js` |
+
+> **⚠️ Do NOT remove or modify these marker comments in `content.js`.** They are required for the build script to function. If the markers are missing, the build will fail with a clear error message.
@@ -0,0 +1,177 @@
+const fs = require('fs');
+const path = require('path');
+const archiver = require('archiver');
+
+const rootDir = path.join(__dirname, '..');
+const extDir = path.join(rootDir, 'extension');
+const distDir = path.join(rootDir, 'dist');
+const baseManifestPath = path.join(extDir, 'manifest.base.json');
+
+// Ensure dist directory exists
+if (fs.existsSync(distDir)) {
+  fs.rmSync(distDir, { recursive: true, force: true });
+}
+fs.mkdirSync(distDir, { recursive: true });
+
+// Sync shared constants from root /shared to /extension/shared
+console.log('Syncing protocol constants...');
+const masterSharedDir = path.join(rootDir, 'shared');
+const extSharedDir = path.join(extDir, 'shared');
+
+if (!fs.existsSync(extSharedDir)) {
+  fs.mkdirSync(extSharedDir, { recursive: true });
+}
+
+const sharedFiles = ['constants.js', 'blacklist.js', 'README.md'];
+for (const file of sharedFiles) {
+  const src = path.join(masterSharedDir, file);
+  const dest = path.join(extSharedDir, file);
+  if (!fs.existsSync(src)) {
+    throw new Error(`CRITICAL: Source shared file missing: ${src}. Aborting build to prevent broken artifacts.`);
+  }
+  fs.copyFileSync(src, dest);
+}
+console.log('✓ constants.js, blacklist.js, and README.md synced to extension/shared/');
+
+// Read the base manifest
+const baseManifest = JSON.parse(fs.readFileSync(baseManifestPath, 'utf8'));
+
+// Helper to copy files, ignoring manifest.json and manifest.base.json
+// Also injects shared constants into content.js
+function copyExtensionFiles(targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  
+  // Read master constants for injection
+  const masterConstantsPath = path.join(rootDir, 'shared', 'constants.js');
+  const constantsContent = fs.readFileSync(masterConstantsPath, 'utf8');
+  
+  // Robust Extraction using flexible regex
+  const eventsMatch = constantsContent.match(/export const EVENTS\s*=\s*({[\s\S]+?});/);
+  const heartbeatMatch = constantsContent.match(/export const HEARTBEAT_INTERVAL\s*=\s*(\d+);/);
+
+  if (!eventsMatch) {
+    throw new Error('CRITICAL: Could not find EVENTS object in shared/constants.js');
+  }
+  if (!heartbeatMatch) {
+    throw new Error('CRITICAL: Could not find HEARTBEAT_INTERVAL in shared/constants.js');
+  }
+
+  const eventsObject = eventsMatch[1];
+  const heartbeatVal = heartbeatMatch[1];
+  
+  const items = fs.readdirSync(extDir);
+  for (const item of items) {
+    if (item === 'manifest.json' || item === 'manifest.base.json') continue;
+    
+    const srcPath = path.join(extDir, item);
+    const destPath = path.join(targetDir, item);
+    
+    if (fs.lstatSync(srcPath).isDirectory()) {
+      fs.cpSync(srcPath, destPath, { recursive: true });
+    } else {
+      if (item === 'content.js') {
+        // Perform injection
+        let content = fs.readFileSync(srcPath, 'utf8');
+        
+        // 1. Inject Events
+        const eStart = '// --- SHARED_EVENTS_INJECT_START ---';
+        const eEnd = '// --- SHARED_EVENTS_INJECT_END ---';
+        const ePattern = new RegExp(`${eStart}[\\s\\S]+?${eEnd}`);
+        const eRep = `${eStart}\n    // This block is automatically updated by /scripts/build-extension.js\n    const EVENTS = ${eventsObject};\n    ${eEnd}`;
+        
+        if (ePattern.test(content)) {
+          content = content.replace(ePattern, eRep);
+        } else {
+          console.warn('⚠️ WARNING: Event markers not found in content.js');
+        }
+
+        // 2. Inject Heartbeat
+        const hStart = '// --- SHARED_HEARTBEAT_INJECT_START ---';
+        const hEnd = '// --- SHARED_HEARTBEAT_INJECT_END ---';
+        const hPattern = new RegExp(`${hStart}[\\s\\S]+?${hEnd}`);
+        const hRep = `${hStart}\n    const HEARTBEAT_INTERVAL_VAL = ${heartbeatVal};\n    ${hEnd}`;
+        
+        if (hPattern.test(content)) {
+          content = content.replace(hPattern, hRep);
+        } else {
+          console.warn('⚠️ WARNING: Heartbeat markers not found in content.js');
+        }
+
+        fs.writeFileSync(destPath, content);
+        console.log('✓ Injected shared constants into content.js');
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+
+// Helper to zip a directory
+function zipDirectory(sourceDir, outPath) {
+  return new Promise((resolve, reject) => {
+    const archive = archiver('zip', { zlib: { level: 9 } });
+    const stream = fs.createWriteStream(outPath);
+
+    archive
+      .directory(sourceDir, false)
+      .on('error', err => reject(err))
+      .pipe(stream);
+
+    stream.on('close', () => resolve());
+    archive.finalize();
+  });
+}
+
+async function buildBrowser(browserName, manifestModifier) {
+  console.log(`Building for ${browserName}...`);
+  const browserDistDir = path.join(distDir, browserName);
+  
+  // 1. Copy files
+  copyExtensionFiles(browserDistDir);
+  
+  // 2. Modify and write manifest
+  const browserManifest = manifestModifier(JSON.parse(JSON.stringify(baseManifest)));
+  fs.writeFileSync(
+    path.join(browserDistDir, 'manifest.json'),
+    JSON.stringify(browserManifest, null, 2)
+  );
+
+  // 3. Zip it
+  const zipPath = path.join(distDir, `koalasync-${browserName}.zip`);
+  await zipDirectory(browserDistDir, zipPath);
+  console.log(`Successfully built and zipped ${browserName} -> ${zipPath}`);
+}
+
+async function run() {
+  try {
+    // Build Chrome
+    await buildBrowser('chrome', (manifest) => {
+      manifest.background = {
+        service_worker: "background.js",
+        type: "module"
+      };
+      return manifest;
+    });
+
+    // Build Firefox
+    await buildBrowser('firefox', (manifest) => {
+      manifest.background = {
+        scripts: ["background.js"],
+        type: "module"
+      };
+      manifest.browser_specific_settings = {
+        gecko: {
+          id: "koalasync@koalastuff.net"
+        }
+      };
+      return manifest;
+    });
+
+    console.log('Build complete!');
+  } catch (error) {
+    console.error('Build failed:', error);
+    process.exit(1);
+  }
+}
+
+run();
@@ -1,12 +0,0 @@
-@echo off
-REM KoalaSync - Protocol Synchronization Script (Windows)
-REM
-REM This script copies the master constants.js file from the shared directory
-REM to the extension directory. Since Chrome Extensions cannot load files
-REM outside their root, this manual sync is required after any changes to
-REM the shared protocol.
-
-if not exist extension\shared mkdir extension\shared
-copy /y shared\constants.js extension\shared\constants.js
-copy /y shared\blacklist.js extension\shared\blacklist.js
-echo ✓ constants.js and blacklist.js synced to extension\shared\
@@ -1,12 +0,0 @@
-#!/bin/sh
-# KoalaSync - Protocol Synchronization Script (Linux/macOS)
-#
-# This script copies the master constants.js file from the shared directory
-# to the extension directory. Since Chrome Extensions cannot load files
-# outside their root, this manual sync is required after any changes to
-# the shared protocol.
-
-mkdir -p extension/shared
-cp shared/constants.js extension/shared/constants.js
-cp shared/blacklist.js extension/shared/blacklist.js
-echo "✓ constants.js and blacklist.js synced to extension/shared/"
@@ -13,17 +13,21 @@ A high-performance Node.js relay server for synchronized video playback.
 Copy `.env.example` to `.env` and configure your settings.
 ```bash
 PORT=3000
-MAX_ROOMS=100
-MAX_PEERS_PER_ROOM=20
+MAX_ROOMS=1000
+MAX_PEERS_PER_ROOM=50
 MIN_VERSION=1.0.0
 ```

 ### Docker (Recommended)
-The server is designed to run in a Docker container.
+The server is available as a pre-built image on GHCR.
 ```bash
-# Build from the repository root
+# Pull from GHCR
+docker pull ghcr.io/shik3i/koalasync:latest
+
+# Or build from the repository root
 docker build -t koala-sync-server -f server/Dockerfile .
 ```
+See [docker-compose.example.yml](../docker-compose.example.yml) in the root directory for a ready-to-use configuration.

 ### Manual Setup
 ```bash
@@ -34,5 +38,6 @@ npm start

 ## Security
 - **Rate Limiting**: IP-based connection limits and socket-based event limits.
- **Token Handshake**: Requires a valid token defined in `shared/constants.js`.
+- **Token Handshake**: Requires a valid token defined in the root `shared/constants.js`.
+- **Single Source of Truth**: The server imports constants directly from the root `shared/` directory.
 - **In-Memory**: Rooms are automatically pruned after 2 hours of inactivity.
@@ -23,7 +23,7 @@ const httpServer = createServer(app);
 // Socket.IO setup with security constraints
 const io = new Server(httpServer, {
    cors: {
-        origin: "*",
+        origin: ["https://sync.koalastuff.net"],
        methods: ["GET", "POST"]
    },
    maxHttpBufferSize: 1024, // 1KB max per message
@@ -85,7 +85,7 @@ setInterval(() => {

 const eventCounts = new Map(); // socketId -> { count, resetTime }

-// Clean up connection counts to prevent memory leak
+// Clean up connection counts and event counts to prevent memory leak
 setInterval(() => {
    const now = Date.now();
    for (const [ip, entry] of connectionCounts.entries()) {
@@ -93,6 +93,11 @@ setInterval(() => {
            connectionCounts.delete(ip);
        }
    }
+    for (const [socketId, entry] of eventCounts.entries()) {
+        if (now > entry.resetTime) {
+            eventCounts.delete(socketId);
+        }
+    }
 }, 60000);

 function checkConnectionRate(ip) {
@@ -113,6 +118,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;
    
@@ -137,6 +187,12 @@ io.on('connection', (socket) => {
    if (clientVersion) {
        const [cMaj, cMin, cPatch] = clientVersion.split('.').map(Number);
        const [mMaj, mMin, mPatch] = MIN_VERSION.split('.').map(Number);
+        if (isNaN(cMaj) || isNaN(cMin) || isNaN(cPatch)) {
+            log('AUTH', `Invalid version format (${clientVersion}) from ${clientIp}`);
+            socket.emit(EVENTS.ERROR, { message: 'Invalid version format' });
+            socket.disconnect(true);
+            return;
+        }
        const tooOld = cMaj < mMaj || (cMaj === mMaj && cMin < mMin) || (cMaj === mMaj && cMin === mMin && cPatch < mPatch);
        if (tooOld) {
            log('AUTH', `Version too old (${clientVersion}) from ${clientIp}`);
@@ -155,7 +211,18 @@ io.on('connection', (socket) => {
            return;
        }
        if (!payload || typeof payload.roomId !== 'string') return;
-        const { roomId, password, peerId, username, tabTitle, mediaTitle, protocolVersion } = payload;
+
+        // --- S-1 & S-5: Sanitize and clamp all incoming fields ---
+        const password        = typeof payload.password === 'string' ? payload.password.substring(0, 128) : null;
+        const peerId          = typeof payload.peerId === 'string' ? payload.peerId.substring(0, 16) : null;
+        const protocolVersion = typeof payload.protocolVersion === 'string' ? payload.protocolVersion.substring(0, 16) : null;
+        const roomId   = String(payload.roomId || '').replace(/[^a-zA-Z0-9\-]/g, '').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 || !peerId) return; // Guard: empty or invalid after sanitization
+
        try {
            // Protocol check
            if (protocolVersion !== '1.0.0') {
@@ -171,14 +238,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 +288,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');
                    }
                }
            }
@@ -266,7 +322,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,17 +342,45 @@ io.on('connection', (socket) => {
                if (room) {
                    room.lastActivity = Date.now();
                    
-                    // Update peer metadata and lastSeen
+                    // --- S-2 & S-3: Sanitize ALL relay fields (strings, numbers, booleans) ---
+                    const clamp    = (val, max) => typeof val === 'string' ? val.substring(0, max) : undefined;
+                    const clampNum = (val, min, max) => typeof val === 'number' && Number.isFinite(val) ? Math.max(min, Math.min(max, val)) : undefined;
+                    const validState = (val) => (val === 'playing' || val === 'paused') ? val : undefined;
+                    const validBool  = (val) => typeof val === 'boolean' ? val : undefined;
+
                    const existing = room.peerData.get(socket.id) || { peerId: mapping.peerId };
                    room.peerData.set(socket.id, { 
                        ...existing,
-                        username: data.username !== undefined ? data.username : existing.username,
-                        tabTitle: data.tabTitle !== undefined ? data.tabTitle : existing.tabTitle,
-                        mediaTitle: data.mediaTitle !== undefined ? data.mediaTitle : existing.mediaTitle,
+                        username:      data.username      !== undefined ? (clamp(data.username, 30)   ?? existing.username)      : existing.username,
+                        tabTitle:      data.tabTitle      !== undefined ? (clamp(data.tabTitle, 100)  ?? existing.tabTitle)      : existing.tabTitle,
+                        mediaTitle:    data.mediaTitle    !== undefined ? (clamp(data.mediaTitle, 100) ?? existing.mediaTitle)   : existing.mediaTitle,
+                        playbackState: data.playbackState !== undefined ? (validState(data.playbackState) ?? existing.playbackState) : existing.playbackState,
+                        currentTime:   data.currentTime   !== undefined ? (clampNum(data.currentTime, 0, 86400) ?? existing.currentTime)   : existing.currentTime,
+                        volume:        data.volume        !== undefined ? (clampNum(data.volume, 0, 1) ?? existing.volume)                 : existing.volume,
+                        muted:         data.muted         !== undefined ? (validBool(data.muted) ?? existing.muted)                       : existing.muted,
                        lastSeen: Date.now()
                    });

-                    socket.to(mapping.roomId).emit(eventName, { ...data, senderId: mapping.peerId });
+                    // --- S-3: Construct clean relay payload — never forward raw client data ---
+                    const relayPayload = {
+                        senderId:        mapping.peerId,
+                        currentTime:     clampNum(data.currentTime, 0, 86400),
+                        targetTime:      clampNum(data.targetTime, 0, 86400),
+                        playbackState:   validState(data.playbackState),
+                        username:        clamp(data.username, 30),
+                        tabTitle:        clamp(data.tabTitle, 100),
+                        mediaTitle:      clamp(data.mediaTitle, 100),
+                        volume:          clampNum(data.volume, 0, 1),
+                        muted:           validBool(data.muted),
+                        peerId:          typeof data.peerId === 'string' ? data.peerId.substring(0, 16) : undefined,
+                        status:          typeof data.status === 'string' ? data.status.substring(0, 16) : undefined,
+                        expectedTitle:   clamp(data.expectedTitle, 100),
+                        title:           clamp(data.title, 100),
+                        actionTimestamp:  clampNum(data.actionTimestamp, 0, Number.MAX_SAFE_INTEGER),
+                    };
+                    // Strip undefined keys for clean wire format
+                    Object.keys(relayPayload).forEach(k => relayPayload[k] === undefined && delete relayPayload[k]);
+                    socket.to(mapping.roomId).emit(eventName, relayPayload);
                }
            }
        });
@@ -313,28 +398,15 @@ 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');
        }
    });

        socket.on(EVENTS.EVENT_ACK, (data) => {
-            if (!data.targetId) return;
+            if (!data || typeof data !== 'object') return;
+            if (typeof data.targetId !== 'string') return;
+            if (data.actionTimestamp !== undefined && (typeof data.actionTimestamp !== 'number' || !Number.isFinite(data.actionTimestamp))) return;
            
            const senderMapping = socketToRoom.get(socket.id);
            const targetSocketId = peerToSocket.get(data.targetId);
@@ -355,22 +427,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');
        }
    });
 });
@@ -383,23 +443,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) {
@@ -413,3 +471,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'));
@@ -4,20 +4,30 @@ This directory contains constants and protocol definitions used by both the exte

 ## Syncing with the Extension
 > [!IMPORTANT]
-> Every time this file is modified, you must run `scripts/sync-constants.sh` to keep the extension's copy up to date.
+> Every time this directory is modified, you must run `node scripts/build-extension.js` to keep the extension's copy up to date.

-Because Chrome Extensions cannot load files outside their root directory, `constants.js` must be copied to `extension/shared/constants.js` whenever it is modified.
+Because Browser Extensions (Manifest V3) cannot load files outside their root directory, all files in this directory must be copied to `extension/shared/` whenever they are modified. The build script handles this automatically.

 ## Security & Versioning Constants
 - `OFFICIAL_SERVER_TOKEN`: A 32-byte hex token required to connect to the official relay server.
- `APP_VERSION`: The current version of the extension. Used by the server to enforce minimum version requirements (Revocation). This must always be in sync with `manifest.json`.
+- `APP_VERSION`: The current version of the extension. Automatically injected from the git tag during CI release builds.
 - `OFFICIAL_SERVER_URL`: The default endpoint for the official KoalaSync relay.
- `ROOM_DATA`: Server response with current room state (peers).
- `PLAY`: Sync command to start playback.
- `PAUSE`: Sync command to pause playback.
- `SEEK`: Sync command to change the current time.
- `PEER_STATUS`: Heartbeat or join/leave notification for peers.
- `FORCE_SYNC_PREPARE`: Phase 1 of Force Sync (Pause & Seek).
- `FORCE_SYNC_ACK`: Peer confirmation of Phase 1 readiness.
- `FORCE_SYNC_EXECUTE`: Phase 2 of Force Sync (Start Playback).
- `ERROR`: Generic error message from the server.
+
+## Protocol Events
+For the complete and current event list, see the `EVENTS` object in [`constants.js`](constants.js). Key events include:
+
+| Event | Direction | Purpose |
+|:------|:----------|:--------|
+| `JOIN_ROOM` | Client → Server | Request to join a room with credentials |
+| `LEAVE_ROOM` | Client → Server | Leave the current room |
+| `ROOM_DATA` | Server → Client | Current room state (peers list) |
+| `PLAY` / `PAUSE` / `SEEK` | Bidirectional relay | Media control commands |
+| `PEER_STATUS` | Bidirectional relay | Heartbeat or join/leave notification |
+| `FORCE_SYNC_PREPARE` | Bidirectional relay | Phase 1: Pause & seek to target time |
+| `FORCE_SYNC_ACK` | Bidirectional relay | Phase 1 confirmation: peer is buffered |
+| `FORCE_SYNC_EXECUTE` | Bidirectional relay | Phase 2: Resume playback simultaneously |
+| `EVENT_ACK` | Server → Client | Delivery confirmation for UI feedback |
+| `EPISODE_LOBBY` | Bidirectional relay | Episode transition: waiting for all peers |
+| `EPISODE_READY` | Bidirectional relay | Episode confirmation: peer has loaded |
+| `GET_ROOMS` / `ROOM_LIST` | Client ↔ Server | Room discovery |
+| `ERROR` | Server → Client | Error message |
@@ -2,7 +2,7 @@
 * blacklist.js
 * 
 * ⚠️ WARNING: This is the SINGLE SOURCE OF TRUTH.
- * If you edit this file, you MUST run /scripts/sync-constants.bat 
+ * If you edit this file, you MUST run: node scripts/build-extension.js
 * to propagate changes to the extension and relay server.
 * 
 * Domains to be filtered out from the tab selection dropdown to reduce "noise".
@@ -78,7 +78,7 @@ export const BLACKLIST_DOMAINS = [
    'myanimelist.net',

    // Development & Utilities
-    'timer.shik3i.net',
+    'timer.koalastuff.net',
    'localhost',
    'zoom.us',
    'teams.microsoft.com',
@@ -2,15 +2,15 @@
 * 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 
+ * If you edit this file, you MUST run: node scripts/build-extension.js
 * to propagate changes to the extension and relay server.
 */

 export const PROTOCOL_VERSION = "1.0.0";
-export const APP_VERSION = "1.1.2";
+export const APP_VERSION = "1.3.1";

-export const OFFICIAL_SERVER_URL = 'wss://sync.shik3i.net';
-export const OFFICIAL_LANDING_PAGE_URL = 'https://koalasync.shik3i.net';
+export const OFFICIAL_SERVER_URL = 'wss://syncserver.koalastuff.net';
+export const OFFICIAL_LANDING_PAGE_URL = 'https://sync.koalastuff.net';
 export const OFFICIAL_SERVER_TOKEN = '62170b705234c4f4807a9b22420bb93cf1a2aacfa4c5d3b47804482babb8eb50';

 export const EVENTS = {
@@ -32,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
@@ -1,31 +1,39 @@
-# KoalaSync Landing Page
+# KoalaSync Website & Invitation Bridge

-This directory contains the static marketing website for KoalaSync. It is built using vanilla HTML, CSS, and JavaScript to ensure maximum performance, zero tracking, and easy hosting.
+This directory contains the KoalaSync website. It serves a dual purpose: it is both the **marketing landing page** and the **technical bridge** for joining synchronized rooms.

-## Features
- **Privacy First**: No external fonts, scripts, or trackers.
- **Modern Tech Aesthetic**: Pure CSS animated gradients and glassmorphism.
- **Smart Join**: Integrated bridge for communication with the KoalaSync browser extension.
+## Core Roles
+
+### 1. Marketing & Onboarding
+Provides a premium, bilingual (EN/DE) overview of features, setup instructions, and direct links to the extension stores.
+
+### 2. The Invitation Bridge (`join.html`)
+The website handles incoming invitation links. When a user clicks a link like `sync.koalastuff.net/join.html#join:roomID:pass`, the website:
+- **Detects the Extension**: Verifies if KoalaSync is installed via the `bridge.js` content script.
+- **Privacy-First Handshake**: The room credentials (ID/Password) are stored in the **URL Hash (#)**. This ensures the sensitive credentials **never reach the web server** and are processed entirely within the user's browser.
+- **Auto-Join**: If the extension is detected, it automatically triggers the join flow without requiring user input.
+
+## Architecture
+
+The website is 100% **Static HTML, CSS, and JS**. 
+- **Zero Backend**: No Node.js, PHP, or databases are required to host the website.
+- **Zero Tracking**: All assets (fonts, icons) are self-hosted to prevent third-party tracking.
+- **Responsive**: Fully optimized for mobile with a native-feel hamburger menu.

 ## Hosting with Caddy

-Caddy is the recommended web server for KoalaSync due to its automatic HTTPS and simple configuration.
+Caddy is the recommended web server. It provides automatic HTTPS and high-performance static file serving.

-### Example Caddyfile
+### Recommended Caddyfile

-To host the website on `koalasync.shik3i.net`, you can use the following configuration:
+For a more comprehensive configuration that includes the Relay Server reverse proxy, see the root [Caddyfile.example](../Caddyfile.example).

 ```caddy
-koalasync.shik3i.net {
-    # Path to the website directory
+sync.koalastuff.net {
    root * /var/www/koalasync/website
-    
-    # Enable static file serving
    file_server
-    
-    # Enable Gzip/Zstd compression
    encode zstd gzip
-    
+
    # Security Headers
    header {
        # Prevent FLoC tracking
@@ -36,16 +44,10 @@ koalasync.shik3i.net {
        X-Frame-Options DENY
        Referrer-Policy no-referrer-when-downgrade
    }
-    
-    # Custom 404 page
-    handle_errors {
-        rewrite * /{err.status_code}.html
-        file_server
-    }
 }
 ```

-### Deployment Steps
-1. Copy the contents of this folder to `/var/www/koalasync/website` on your server.
-2. Update the path in your `Caddyfile`.
-3. Reload Caddy: `caddy reload`.
+## Local Development
+
+1. Open `index.html` directly in any browser.
+2. To test the invitation flow locally, use a local server (e.g., `npx serve .`) and navigate to `http://localhost:5000/join.html#join:test-room:test-pass`.
@@ -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);
                        }
                    }
@@ -147,14 +161,18 @@ document.addEventListener('DOMContentLoaded', () => {

            if (success) {
                if (icon) icon.textContent = '✅';
-                title.textContent = 'Erfolgreich!';
+                const isDE = document.documentElement.classList.contains('lang-de');
+                title.textContent = isDE ? 'Erfolgreich!' : 'Success!';
                
                let count = 3;
                const updateCountdown = () => {
-                    desc.innerHTML = `Du bist dem Raum beigetreten. <br><span style="color:var(--accent); font-weight:bold;">Dieser Tab schließt sich in ${count} Sekunden...</span>`;
+                    const closingMsg = isDE 
+                        ? `Du bist dem Raum beigetreten. <br><span style="color:var(--accent); font-weight:bold;">Dieser Tab schließt sich in ${count} Sekunden...</span>`
+                        : `You joined the room. <br><span style="color:var(--accent); font-weight:bold;">This tab will close in ${count} seconds...</span>`;
+                    desc.innerHTML = closingMsg;
                    if (count <= 0) {
                        window.close();
-                        desc.textContent = 'Beitritt erfolgreich! Du kannst diesen Tab jetzt manuell schließen.';
+                        desc.textContent = isDE ? 'Beitritt erfolgreich! Du kannst diesen Tab jetzt manuell schließen.' : 'Joined successfully! You can close this tab manually.';
                    } else {
                        count--;
                        setTimeout(updateCountdown, 1000);
@@ -162,12 +180,15 @@ document.addEventListener('DOMContentLoaded', () => {
                };
                updateCountdown();
                
-                actions.innerHTML = '<button class="primary" onclick="window.close()" style="background:var(--success); width: 100%;">TAB JETZT SCHLIESSEN</button>';
+                const closeLabel = isDE ? 'TAB JETZT SCHLIESSEN' : 'CLOSE TAB NOW';
+                actions.innerHTML = `<button class="primary" onclick="window.close()" style="background:var(--success); width: 100%;">${closeLabel}</button>`;
            } else {
                if (icon) icon.textContent = '❌';
-                title.textContent = 'Fehler';
-                desc.textContent = `Beitritt fehlgeschlagen: ${message}`;
-                actions.innerHTML = '<button class="primary" onclick="location.reload()" style="width: 100%;">ERNEUT VERSUCHEN</button>';
+                const isDE = document.documentElement.classList.contains('lang-de');
+                title.textContent = isDE ? 'Fehler' : 'Error';
+                desc.textContent = isDE ? `Beitritt fehlgeschlagen: ${message}` : `Join failed: ${message}`;
+                const retryLabel = isDE ? 'ERNEUT VERSUCHEN' : 'TRY AGAIN';
+                actions.innerHTML = `<button class="primary" onclick="location.reload()" style="width: 100%;">${retryLabel}</button>`;
            }
        } else {
            const banner = document.getElementById('koala-banner');
@@ -178,7 +199,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);
                }
            }
        }
@@ -1,11 +1,32 @@
 <!DOCTYPE html>
-<html lang="de">
+<html lang="en">
 <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Datenschutz | KoalaSync</title>
+    <title>Datenschutz / Privacy Policy | KoalaSync</title>
    <link rel="stylesheet" href="style.css">
    <link rel="icon" type="image/png" href="assets/logo.png">
+    <meta name="robots" content="noindex">
+    <script>
+        (function() {
+            var savedLang = localStorage.getItem('koala_lang');
+            var browserLang = navigator.language.startsWith('de') ? 'de' : 'en';
+            var activeLang = savedLang || browserLang;
+            document.documentElement.classList.add('lang-' + activeLang);
+            document.documentElement.lang = activeLang;
+        })();
+        
+        function toggleLanguage(e) {
+            if(e) e.preventDefault();
+            var html = document.documentElement;
+            var currentIsEnglish = html.classList.contains('lang-en');
+            var newLang = currentIsEnglish ? 'de' : 'en';
+            html.classList.remove('lang-en', 'lang-de');
+            html.classList.add('lang-' + newLang);
+            html.lang = newLang;
+            localStorage.setItem('koala_lang', newLang);
+        }
+    </script>
 </head>
 <body>
    <div class="bg-blobs">
@@ -20,54 +41,110 @@
                <img src="assets/logo.png" alt="KoalaSync Logo">
                <span>KoalaSync</span>
            </a>
+            <button class="hamburger" onclick="document.querySelector('.nav-links').classList.toggle('open')" aria-label="Menu">☰</button>
            <div class="nav-links">
-                <a href="index.html">Home</a>
+                <a href="index.html"><span lang="de">Startseite</span><span lang="en">Home</span></a>
                <a href="https://github.com/shik3i/KoalaSync" target="_blank">GitHub</a>
+                <a class="lang-toggle" onclick="toggleLanguage(event)">🌍 EN/DE</a>
            </div>
        </div>
    </nav>

    <main class="legal-content">
        <div class="legal-card" data-reveal style="padding: 2rem;">
-            <h1>Datenschutz</h1>
-            <p style="text-align: center; text-transform: uppercase; letter-spacing: 0.1em; font-size: 0.8rem; border-bottom: 1px solid var(--glass-border); padding-bottom: 1.5rem; margin-bottom: 2rem;">
+            <h1 lang="de">Datenschutz</h1>
+            <h1 lang="en">Privacy Policy</h1>
+            <p lang="de" style="text-align: center; text-transform: uppercase; letter-spacing: 0.1em; font-size: 0.8rem; border-bottom: 1px solid var(--glass-border); padding-bottom: 1.5rem; margin-bottom: 2rem;">
                Sicherheit & Privatsphäre
            </p>
+            <p lang="en" style="text-align: center; text-transform: uppercase; letter-spacing: 0.1em; font-size: 0.8rem; border-bottom: 1px solid var(--glass-border); padding-bottom: 1.5rem; margin-bottom: 2rem;">
+                Security & Privacy
+            </p>

            <section>
-                <h2>1. Hosting & Logfiles</h2>
-                <p>
+                <h2>
+                    <span lang="de">1. Hosting & Logfiles</span>
+                    <span lang="en">1. Hosting & Logfiles</span>
+                </h2>
+                <p lang="de">
                    Diese Seite wird auf einem privaten Server gehostet. Zur Gewährleistung der Stabilität werden standardmäßige Server-Logs (IP, Browser, Zeit) erhoben, aber nicht mit Personen verknüpft und nach 7 Tagen automatisch gelöscht.
                </p>
+                <p lang="en">
+                    This site is hosted on a private server. To ensure stability, standard server logs (IP, browser, time) are collected, but not linked to individuals and are automatically deleted after 7 days.
+                </p>
            </section>

            <section>
-                <h2>2. Keine Drittanbieter & Tracking</h2>
-                <p>
+                <h2>
+                    <span lang="de">2. Keine Drittanbieter & Open Source</span>
+                    <span lang="en">2. No Third Parties & Open Source</span>
+                </h2>
+                <p lang="de">
                    KoalaSync verzichtet bewusst auf Analyse-Tools, Tracking-Cookies oder Werbenetzwerke. Wir laden keine Ressourcen von Drittanbietern (wie Google Fonts) nach, um Ihre Privatsphäre maximal zu schützen.
                </p>
+                <p lang="de" style="margin-top: 0.5rem;">
+                    Da KoalaSync vollständig Open Source ist, kann zudem jede Zeile Code auf unserem <a href="https://github.com/shik3i/KoalaSync" target="_blank" style="color: var(--accent);">GitHub-Repository</a> öffentlich eingesehen und auf Sicherheit geprüft werden.
+                </p>
+                <p lang="en">
+                    KoalaSync deliberately avoids analytics tools, tracking cookies, or advertising networks. We do not load any third-party resources (such as Google Fonts) to maximize the protection of your privacy.
+                </p>
+                <p lang="en" style="margin-top: 0.5rem;">
+                    Since KoalaSync is 100% open-source, every single line of code can also be publicly viewed and audited for security on our <a href="https://github.com/shik3i/KoalaSync" target="_blank" style="color: var(--accent);">GitHub repository</a>.
+                </p>
            </section>

            <section>
-                <h2>3. Relay-Server Architektur</h2>
-                <p>
+                <h2>
+                    <span lang="de">3. Relay-Server Architektur</span>
+                    <span lang="en">3. Relay Server Architecture</span>
+                </h2>
+                <p lang="de">
                    Unser Relay-Server arbeitet ausschließlich im Arbeitsspeicher (RAM). Nachrichten zwischen Teilnehmern werden nicht auf Festplatten gespeichert und sind flüchtig. Sobald ein Raum geschlossen wird, werden alle zugehörigen Metadaten sofort gelöscht.
                </p>
+                <p lang="en">
+                    Our relay server operates exclusively in memory (RAM). Messages between participants are not stored on hard drives and are volatile. As soon as a room is closed, all associated metadata is immediately deleted.
+                </p>
            </section>

            <section>
-                <h2>4. Brute-Force Schutz</h2>
-                <p>
+                <h2>
+                    <span lang="de">4. Browser-Erweiterung (Extension)</span>
+                    <span lang="en">4. Browser Extension</span>
+                </h2>
+                <p lang="de">
+                    Um die geräteübergreifende Synchronisation zu ermöglichen, erfasst die KoalaSync Browser-Erweiterung temporär Daten des aktuell aktiven Video-Tabs (z. B. Tab-Titel, Medien-Metadaten wie den Videotitel sowie den Wiedergabestatus). Diese Daten werden ausschließlich zur Synchronisation an die anderen Teilnehmer in Ihrem Raum gesendet. Es wird ausdrücklich <strong>kein allgemeiner Browserverlauf (Browsing History)</strong> ausgelesen, gespeichert oder übermittelt.
+                </p>
+                <p lang="en">
+                    To enable cross-device synchronization, the KoalaSync browser extension temporarily captures data from the currently active video tab (e.g., tab title, media metadata like the video title, and playback state). This data is exclusively sent to other participants in your room for synchronization. We explicitly <strong>do not read, store, or transmit your general browsing history</strong>.
+                </p>
+            </section>
+
+            <section>
+                <h2>
+                    <span lang="de">5. Brute-Force Schutz</span>
+                    <span lang="en">5. Brute-Force Protection</span>
+                </h2>
+                <p lang="de">
                    Zur Sicherheit unserer Nutzer speichern wir fehlgeschlagene Login-Versuche (IP-Adresse und Raum-ID) für maximal 15 Minuten im RAM, um automatisierte Angriffe zu verhindern. Diese Daten werden danach rückstandslos gelöscht.
                </p>
+                <p lang="en">
+                    For the security of our users, we store failed login attempts (IP address and room ID) for a maximum of 15 minutes in RAM to prevent automated attacks. This data is deleted without a trace afterwards.
+                </p>
            </section>

            <section>
-                <h2>5. Ihre Rechte</h2>
-                <p>
+                <h2>
+                    <span lang="de">6. Ihre Rechte</span>
+                    <span lang="en">6. Your Rights</span>
+                </h2>
+                <p lang="de">
                    Sie haben das Recht auf Auskunft, Berichtigung oder Löschung Ihrer Daten. Da wir jedoch keine personenbezogenen Daten dauerhaft speichern, ist eine Zuordnung zu Ihrer Person in der Regel technisch nicht möglich.
                </p>
-                <p>Kontakt bei Fragen: <span style="color: var(--accent); cursor: pointer; text-decoration: underline;" onclick="this.innerHTML='koalasync_datenschutz' + '@' + 'koalamail.rocks'">[E-Mail anzeigen]</span></p>
+                <p lang="en">
+                    You have the right to information, correction, or deletion of your data. However, since we do not store any personal data permanently, linking data to your person is technically impossible in most cases.
+                </p>
+                <p lang="de">Kontakt bei Fragen: <span style="color: var(--accent); cursor: pointer; text-decoration: underline;" onclick="this.innerHTML='koalasync_datenschutz' + '@' + 'koalamail.rocks'">[E-Mail anzeigen]</span></p>
+                <p lang="en">Contact for questions: <span style="color: var(--accent); cursor: pointer; text-decoration: underline;" onclick="this.innerHTML='koalasync_datenschutz' + '@' + 'koalamail.rocks'">[Show Email]</span></p>
            </section>
        </div>
    </main>
@@ -75,10 +152,11 @@
    <footer>
        <div class="container">
            <p>&copy; 2026 KoalaSync. Open source under the MIT License.</p>
-            <p style="font-size: 0.8rem; margin-top: 0.5rem;">No data is stored on our servers. Pure RAM-based relay.</p>
+            <p lang="de" style="font-size: 0.8rem; margin-top: 0.5rem;">Keine Daten werden auf unseren Servern gespeichert. Reines RAM-basiertes Relay.</p>
+            <p lang="en" style="font-size: 0.8rem; margin-top: 0.5rem;">No data is stored on our servers. Pure RAM-based relay.</p>
            <div style="margin-top: 1.5rem; font-size: 0.8rem; display: flex; justify-content: center; gap: 1.5rem;">
-                <a href="impressum.html" style="color: var(--text-muted); text-decoration: none;">Impressum</a>
-                <a href="datenschutz.html" style="color: var(--text-muted); text-decoration: none;">Datenschutz</a>
+                <a href="impressum.html" style="color: var(--text-muted); text-decoration: none;"><span lang="de">Impressum</span><span lang="en">Legal Notice</span></a>
+                <a href="datenschutz.html" style="color: var(--text-muted); text-decoration: none;"><span lang="de">Datenschutz</span><span lang="en">Privacy Policy</span></a>
            </div>
        </div>
    </footer>
@@ -1,11 +1,32 @@
 <!DOCTYPE html>
-<html lang="de">
+<html lang="en">
 <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Impressum | KoalaSync</title>
+    <title>Impressum / Legal Notice | KoalaSync</title>
    <link rel="stylesheet" href="style.css">
    <link rel="icon" type="image/png" href="assets/logo.png">
+    <meta name="robots" content="noindex">
+    <script>
+        (function() {
+            var savedLang = localStorage.getItem('koala_lang');
+            var browserLang = navigator.language.startsWith('de') ? 'de' : 'en';
+            var activeLang = savedLang || browserLang;
+            document.documentElement.classList.add('lang-' + activeLang);
+            document.documentElement.lang = activeLang;
+        })();
+        
+        function toggleLanguage(e) {
+            if(e) e.preventDefault();
+            var html = document.documentElement;
+            var currentIsEnglish = html.classList.contains('lang-en');
+            var newLang = currentIsEnglish ? 'de' : 'en';
+            html.classList.remove('lang-en', 'lang-de');
+            html.classList.add('lang-' + newLang);
+            html.lang = newLang;
+            localStorage.setItem('koala_lang', newLang);
+        }
+    </script>
 </head>
 <body>
    <div class="bg-blobs">
@@ -20,57 +41,95 @@
                <img src="assets/logo.png" alt="KoalaSync Logo">
                <span>KoalaSync</span>
            </a>
+            <button class="hamburger" onclick="document.querySelector('.nav-links').classList.toggle('open')" aria-label="Menu">☰</button>
            <div class="nav-links">
-                <a href="index.html">Home</a>
+                <a href="index.html"><span lang="de">Startseite</span><span lang="en">Home</span></a>
                <a href="https://github.com/shik3i/KoalaSync" target="_blank">GitHub</a>
+                <a class="lang-toggle" onclick="toggleLanguage(event)">🌍 EN/DE</a>
            </div>
        </div>
    </nav>

    <main class="legal-content">
        <div class="legal-card" data-reveal style="padding: 2rem;">
-            <h1>Impressum</h1>
-            <p style="text-align: center; text-transform: uppercase; letter-spacing: 0.1em; font-size: 0.8rem; border-bottom: 1px solid var(--glass-border); padding-bottom: 1.5rem; margin-bottom: 2rem;">
+            <h1 lang="de">Impressum</h1>
+            <h1 lang="en">Legal Notice</h1>
+            <p lang="de" style="text-align: center; text-transform: uppercase; letter-spacing: 0.1em; font-size: 0.8rem; border-bottom: 1px solid var(--glass-border); padding-bottom: 1.5rem; margin-bottom: 2rem;">
                Transparenz & Identifikation
            </p>
+            <p lang="en" style="text-align: center; text-transform: uppercase; letter-spacing: 0.1em; font-size: 0.8rem; border-bottom: 1px solid var(--glass-border); padding-bottom: 1.5rem; margin-bottom: 2rem;">
+                Transparency & Identification
+            </p>

            <section>
-                <h2>Betreiber & Kontakt</h2>
-                <p>Administrator KoalaSync (Privatperson)</p>
-                <p>E-Mail: <span style="color: var(--accent); cursor: pointer; text-decoration: underline;" onclick="this.innerHTML='koalasync_admin' + '@' + 'koalamail.rocks'">[E-Mail anzeigen]</span></p>
+                <h2>
+                    <span lang="de">Betreiber & Kontakt</span>
+                    <span lang="en">Operator & Contact</span>
+                </h2>
+                <p lang="de">Administrator KoalaSync (Privatperson)</p>
+                <p lang="en">Administrator KoalaSync (Private Individual)</p>
+                <p lang="de">E-Mail: <span style="color: var(--accent); cursor: pointer; text-decoration: underline;" onclick="this.innerHTML='koalasync_admin' + '@' + 'koalamail.rocks'">[E-Mail anzeigen]</span></p>
+                <p lang="en">E-Mail: <span style="color: var(--accent); cursor: pointer; text-decoration: underline;" onclick="this.innerHTML='koalasync_admin' + '@' + 'koalamail.rocks'">[Show Email]</span></p>
            </section>

            <section style="opacity: 0.8;">
-                <h2>Privatprojekt-Hinweis</h2>
-                <p>
+                <h2>
+                    <span lang="de">Privatprojekt-Hinweis</span>
+                    <span lang="en">Private Project Notice</span>
+                </h2>
+                <p lang="de">
                    Diese Website ist ein rein privates Hobby-Projekt und dient keinen geschäftsmäßigen Zwecken. 
                    Eine Impressumspflicht nach § 5 DDG (ehemals TMG) besteht daher nicht. 
                    Diese Angaben erfolgen rein freiwillig zur Transparenz gegenüber der Community.
                </p>
+                <p lang="en">
+                    This website is a purely private hobby project and does not serve any commercial purposes.
+                    Therefore, there is no obligation to provide a legal notice according to § 5 DDG (formerly TMG).
+                    This information is provided voluntarily for transparency towards the community.
+                </p>
            </section>

            <section>
-                <h2>Haftung für Inhalte</h2>
-                <p>
+                <h2>
+                    <span lang="de">Haftung für Inhalte</span>
+                    <span lang="en">Liability for Content</span>
+                </h2>
+                <p lang="de">
                    Gemäß § 7 Abs.1 DDG sind wir für eigene Inhalte verantwortlich. Nach §§ 8 bis 10 DDG sind wir jedoch nicht verpflichtet, 
                    übermittelte oder gespeicherte fremde Informationen zu überwachen.
                </p>
-            </section>
-
-            <section>
-                <h2>Haftung für Links</h2>
-                <p>
-                    Unser Angebot enthält Links zu externen Websites Dritter. Auf deren Inhalte haben wir keinen Einfluss und 
-                    können daher keine Gewähr für diese fremden Inhalte übernehmen.
+                <p lang="en">
+                    According to § 7 Abs.1 DDG we are responsible for our own content. According to §§ 8 to 10 DDG, however, we are not obligated to monitor transmitted or stored third-party information.
                </p>
            </section>

            <section>
-                <h2>Urheberrecht</h2>
-                <p>
+                <h2>
+                    <span lang="de">Haftung für Links</span>
+                    <span lang="en">Liability for Links</span>
+                </h2>
+                <p lang="de">
+                    Unser Angebot enthält Links zu externen Websites Dritter. Auf deren Inhalte haben wir keinen Einfluss und 
+                    können daher keine Gewähr für diese fremden Inhalte übernehmen.
+                </p>
+                <p lang="en">
+                    Our offer contains links to external third-party websites. We have no influence on their content and therefore cannot assume any liability for these external contents.
+                </p>
+            </section>
+
+            <section>
+                <h2>
+                    <span lang="de">Urheberrecht</span>
+                    <span lang="en">Copyright</span>
+                </h2>
+                <p lang="de">
                    Die durch die Seitenbetreiber erstellten Inhalte auf diesen Seiten unterliegen dem deutschen Urheberrecht. 
                    Vervielfältigung, Bearbeitung und jede Art der Verwertung außerhalb der Grenzen des Urheberrechtes bedürfen der schriftlichen Zustimmung.
                </p>
+                <p lang="en">
+                    The content and works created by the site operators on these pages are subject to German copyright law.
+                    Duplication, processing, and any kind of exploitation outside the limits of copyright require written consent.
+                </p>
            </section>
        </div>
    </main>
@@ -78,10 +137,11 @@
    <footer>
        <div class="container">
            <p>&copy; 2026 KoalaSync. Open source under the MIT License.</p>
-            <p style="font-size: 0.8rem; margin-top: 0.5rem;">No data is stored on our servers. Pure RAM-based relay.</p>
+            <p lang="de" style="font-size: 0.8rem; margin-top: 0.5rem;">Keine Daten werden auf unseren Servern gespeichert. Reines RAM-basiertes Relay.</p>
+            <p lang="en" style="font-size: 0.8rem; margin-top: 0.5rem;">No data is stored on our servers. Pure RAM-based relay.</p>
            <div style="margin-top: 1.5rem; font-size: 0.8rem; display: flex; justify-content: center; gap: 1.5rem;">
-                <a href="impressum.html" style="color: var(--text-muted); text-decoration: none;">Impressum</a>
-                <a href="datenschutz.html" style="color: var(--text-muted); text-decoration: none;">Datenschutz</a>
+                <a href="impressum.html" style="color: var(--text-muted); text-decoration: none;"><span lang="de">Impressum</span><span lang="en">Legal Notice</span></a>
+                <a href="datenschutz.html" style="color: var(--text-muted); text-decoration: none;"><span lang="de">Datenschutz</span><span lang="en">Privacy Policy</span></a>
            </div>
        </div>
    </footer>
@@ -10,8 +10,33 @@
    <link rel="icon" type="image/png" href="assets/logo.png">
    <meta property="og:title" content="KoalaSync | Sync your videos">
    <meta property="og:description" content="Watch together, stay in sync. Privacy-first video synchronization.">
-    <meta property="og:image" content="assets/hero.png">
+    <meta property="og:image" content="https://sync.koalastuff.net/assets/logo.png">
    <meta property="og:type" content="website">
+
+    <script>
+        (function() {
+            var savedLang = localStorage.getItem('koala_lang');
+            var browserLang = navigator.language.startsWith('de') ? 'de' : 'en';
+            var activeLang = savedLang || browserLang;
+            document.documentElement.classList.add('lang-' + activeLang);
+            document.documentElement.lang = activeLang;
+            var titles = { en: 'KoalaSync | Real-time Video Synchronization for Friends', de: 'KoalaSync | Echtzeit-Video-Synchronisation für Freunde' };
+            document.title = titles[activeLang] || titles.en;
+        })();
+        
+        function toggleLanguage(e) {
+            if(e) e.preventDefault();
+            var html = document.documentElement;
+            var currentIsEnglish = html.classList.contains('lang-en');
+            var newLang = currentIsEnglish ? 'de' : 'en';
+            html.classList.remove('lang-en', 'lang-de');
+            html.classList.add('lang-' + newLang);
+            html.lang = newLang;
+            localStorage.setItem('koala_lang', newLang);
+            var titles = { en: 'KoalaSync | Real-time Video Synchronization for Friends', de: 'KoalaSync | Echtzeit-Video-Synchronisation für Freunde' };
+            document.title = titles[newLang] || titles.en;
+        }
+    </script>
 </head>
 <body>

@@ -27,10 +52,12 @@
                <img src="assets/logo.png" alt="KoalaSync Logo">
                <span>KoalaSync</span>
            </div>
+            <button class="hamburger" onclick="document.querySelector('.nav-links').classList.toggle('open')" aria-label="Menu">☰</button>
            <div class="nav-links">
-                <a href="#features">Features</a>
-                <a href="#how-it-works">How it works</a>
+                <a href="#features"><span lang="en">Features</span><span lang="de">Funktionen</span></a>
+                <a href="#how-it-works"><span lang="en">How it works</span><span lang="de">So funktioniert's</span></a>
                <a href="https://github.com/Shik3i/KoalaSync" target="_blank">GitHub</a>
+                <a class="lang-toggle" onclick="toggleLanguage(event)">🌍 EN/DE</a>
            </div>
        </div>
    </nav>
@@ -38,12 +65,23 @@
    <header class="hero">
        <div class="container hero-grid">
            <div class="hero-text">
-                <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="version-badge" data-reveal><span lang="en">v1.3.1 OUT NOW</span><span lang="de">v1.3.1 JETZT VERFÜGBAR</span></div>
+                <h1 data-reveal>
+                    <span lang="en">Watch Together.<br>Sync Perfectly.</span>
+                    <span lang="de">Gemeinsam schauen.<br>Perfekt synchron.</span>
+                </h1>
+                <h2 class="hero-subtitle" data-reveal>
+                    <span lang="en">The ultimate free watch party extension for YouTube, Twitch, and local MP4s.</span>
+                    <span lang="de">Die ultimative, kostenlose Watch-Party-Erweiterung für YouTube, Twitch und lokale MP4s.</span>
+                </h2>
                <div class="cta-group" data-reveal>
                    <a href="#" class="btn btn-primary">
                        <img src="assets/chrome.svg" width="20" style="filter: brightness(100)">
-                        Add to Chrome
+                        <span lang="en">Add to Chrome</span><span lang="de">Zu Chrome hinzufügen</span>
+                    </a>
+                    <a href="#" class="btn btn-primary" style="background: #e66000;">
+                        🦊
+                        <span lang="en">Add to Firefox</span><span lang="de">Zu Firefox hinzufügen</span>
                    </a>
                    <a href="https://github.com/Shik3i/KoalaSync" class="btn btn-secondary">
                        GitHub Repo
@@ -55,55 +93,74 @@

    <section id="features">
        <div class="container">
-            <h2 style="font-size: 2.5rem; text-align: center; margin-bottom: 1rem;">Why KoalaSync?</h2>
-            <p style="text-align: center; color: var(--text-muted); margin-bottom: 4rem;">Built for performance, privacy, and simplicity.</p>
+            <h2 style="font-size: 2.5rem; text-align: center; margin-bottom: 1rem;">
+                <span lang="en">Why KoalaSync?</span><span lang="de">Warum KoalaSync?</span>
+            </h2>
+            <p style="text-align: center; color: var(--text-muted); margin-bottom: 4rem;">
+                <span lang="en">Built for performance, privacy, and simplicity.</span><span lang="de">Entwickelt für Leistung, Privatsphäre und Einfachheit.</span>
+            </p>
            
            <div class="features-grid">
                <div class="feature-card" data-reveal>
                    <div class="feature-icon">⚡</div>
-                    <h3>Real-time Sync</h3>
-                    <p>Proprietary two-phase synchronization protocol ensures sub-millisecond precision across all peers.</p>
+                    <h3><span lang="en">Real-time Sync</span><span lang="de">Echtzeit-Synchronisation</span></h3>
+                    <p lang="en">Proprietary two-phase synchronization protocol ensures sub-millisecond precision across all peers.</p>
+                    <p lang="de">Das proprietäre Zwei-Phasen-Synchronisationsprotokoll gewährleistet Sub-Millisekunden-Präzision für alle Teilnehmer.</p>
+                </div>
+                <div class="feature-card" data-reveal>
+                    <div class="feature-icon">🎬</div>
+                    <h3><span lang="en">Episode Auto-Sync</span><span lang="de">Automatische Episoden-Synchronisation</span></h3>
+                    <p lang="en">New in v1.3.1: Perfectly sync series binges. All peers wait until everyone has loaded the next episode.</p>
+                    <p lang="de">Neu in v1.3.1: Perfekt synchronisiertes Serien-Bingeing. Alle warten, bis jeder die nächste Episode geladen hat.</p>
                </div>
                <div class="feature-card" data-reveal>
                    <div class="feature-icon">🛡️</div>
-                    <h3>Privacy First</h3>
-                    <p>Zero data persistence. Our relay server runs entirely in RAM and collects no telemetry or logs.</p>
+                    <h3><span lang="en">Privacy First</span><span lang="de">Privatsphäre zuerst</span></h3>
+                    <p lang="en">Zero data persistence. Our relay server runs entirely in RAM and collects no telemetry or logs.</p>
+                    <p lang="de">Keine Datenspeicherung. Unser Relay-Server läuft komplett im RAM und sammelt weder Telemetrie noch Logs.</p>
                </div>
                <div class="feature-card" data-reveal>
                    <div class="feature-icon">⭐</div>
-                    <h3>Smart Match</h3>
-                    <p>Find the right tab instantly. KoalaSync highlights and sorts matching video tabs for you.</p>
+                    <h3><span lang="en">Smart Match</span><span lang="de">Intelligente Zuordnung</span></h3>
+                    <p lang="en">Find the right tab instantly. KoalaSync highlights and sorts matching video tabs for you.</p>
+                    <p lang="de">Finden Sie sofort den richtigen Tab. KoalaSync markiert und sortiert passende Video-Tabs für Sie.</p>
                </div>
            </div>
+
        </div>
    </section>

    <section id="how-it-works" style="background: rgba(255,255,255,0.02)">
        <div class="container">
-            <h2 style="font-size: 2.5rem; text-align: center; margin-bottom: 4rem;">Getting Started</h2>
+            <h2 style="font-size: 2.5rem; text-align: center; margin-bottom: 4rem;">
+                <span lang="en">Getting Started</span><span lang="de">Loslegen</span>
+            </h2>
            
            <div class="steps">
                <div class="step">
                    <div class="step-text" data-reveal>
                        <div class="step-num">01</div>
-                        <h3>Install Extension</h3>
-                        <p>Add KoalaSync to your browser from the Chrome Web Store or download the latest developer ZIP from GitHub.</p>
+                        <h3><span lang="en">Install Extension</span><span lang="de">Erweiterung installieren</span></h3>
+                        <p lang="en">Add KoalaSync to your browser from the Chrome Web Store or download the latest developer ZIP from GitHub.</p>
+                        <p lang="de">Fügen Sie KoalaSync aus dem Chrome Web Store zu Ihrem Browser hinzu oder laden Sie die neueste Entwickler-ZIP von GitHub herunter.</p>
                    </div>
                    <div style="background: var(--card); height: 200px; border-radius: 20px; border: 1px solid var(--glass-border);"></div>
                </div>
                <div class="step">
                    <div class="step-text" data-reveal>
                        <div class="step-num">02</div>
-                        <h3>Create a Room</h3>
-                        <p>Open the extension, enter a Room ID and Password, and hit Join. Your secure synchronization space is ready.</p>
+                        <h3><span lang="en">Create a Room</span><span lang="de">Raum erstellen</span></h3>
+                        <p lang="en">Open the extension, enter a Room ID and Password, and hit Join. Your secure synchronization space is ready.</p>
+                        <p lang="de">Öffnen Sie die Erweiterung, geben Sie eine Raum-ID und ein Passwort ein und klicken Sie auf Beitreten. Ihr sicherer Synchronisationsraum ist bereit.</p>
                    </div>
                    <div style="background: var(--card); height: 200px; border-radius: 20px; border: 1px solid var(--glass-border);"></div>
                </div>
                <div class="step">
                    <div class="step-text" data-reveal>
                        <div class="step-num">03</div>
-                        <h3>Share & Sync</h3>
-                        <p>Send the invite link to your friends. Once they join, select your video tab and enjoy perfectly synced playback.</p>
+                        <h3><span lang="en">Share & Sync</span><span lang="de">Teilen & Synchronisieren</span></h3>
+                        <p lang="en">Send the invite link to your friends. Once they join, select your video tab and enjoy perfectly synced playback.</p>
+                        <p lang="de">Senden Sie den Einladungslink an Ihre Freunde. Sobald sie beitreten, wählen Sie Ihren Video-Tab aus und genießen Sie die perfekt synchronisierte Wiedergabe.</p>
                    </div>
                    <div style="background: var(--card); height: 200px; border-radius: 20px; border: 1px solid var(--glass-border);"></div>
                </div>
@@ -113,19 +170,24 @@

    <section style="text-align: center;">
        <div class="container">
-            <h2 data-reveal>Ready to sync?</h2>
-            <p data-reveal style="margin-bottom: 2rem; color: var(--text-muted);">Join thousands of users watching together.</p>
-            <a href="https://github.com/Shik3i/KoalaSync" class="btn btn-primary" data-reveal>View on GitHub</a>
+            <h2 data-reveal><span lang="en">Ready to sync?</span><span lang="de">Bereit zum Synchronisieren?</span></h2>
+            <p data-reveal style="margin-bottom: 2rem; color: var(--text-muted);">
+                <span lang="en">Join thousands of users watching together.</span><span lang="de">Schließen Sie sich Tausenden von Nutzern an, die bereits zusammen schauen.</span>
+            </p>
+            <a href="https://github.com/Shik3i/KoalaSync" class="btn btn-primary" data-reveal>
+                <span lang="en">View on GitHub</span><span lang="de">Auf GitHub ansehen</span>
+            </a>
        </div>
    </section>

    <footer>
        <div class="container">
            <p>&copy; 2026 KoalaSync. Open source under the MIT License.</p>
-            <p style="font-size: 0.8rem; margin-top: 0.5rem;">No data is stored on our servers. Pure RAM-based relay.</p>
+            <p lang="en" style="font-size: 0.8rem; margin-top: 0.5rem;">No data is stored on our servers. Pure RAM-based relay.</p>
+            <p lang="de" style="font-size: 0.8rem; margin-top: 0.5rem;">Keine Daten werden auf unseren Servern gespeichert. Reines RAM-basiertes Relay.</p>
            <div style="margin-top: 1.5rem; font-size: 0.8rem; display: flex; justify-content: center; gap: 1.5rem;">
-                <a href="impressum.html" style="color: var(--text-muted); text-decoration: none;">Impressum</a>
-                <a href="datenschutz.html" style="color: var(--text-muted); text-decoration: none;">Datenschutz</a>
+                <a href="impressum.html" style="color: var(--text-muted); text-decoration: none;"><span lang="en">Legal Notice</span><span lang="de">Impressum</span></a>
+                <a href="datenschutz.html" style="color: var(--text-muted); text-decoration: none;"><span lang="en">Privacy Policy</span><span lang="de">Datenschutz</span></a>
            </div>
        </div>
    </footer>
@@ -1,11 +1,36 @@
 <!DOCTYPE html>
-<html lang="de">
+<html lang="en">
 <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Beitreten | KoalaSync</title>
+    <title>Join Room | KoalaSync</title>
    <link rel="stylesheet" href="style.css">
    <link rel="icon" type="image/png" href="assets/logo.png">
+    <meta name="robots" content="noindex">
+    <script>
+        (function() {
+            var savedLang = localStorage.getItem('koala_lang');
+            var browserLang = navigator.language.startsWith('de') ? 'de' : 'en';
+            var activeLang = savedLang || browserLang;
+            document.documentElement.classList.add('lang-' + activeLang);
+            document.documentElement.lang = activeLang;
+            var titles = { en: 'Join Room | KoalaSync', de: 'Raum beitreten | KoalaSync' };
+            document.title = titles[activeLang] || titles.en;
+        })();
+        
+        function toggleLanguage(e) {
+            if(e) e.preventDefault();
+            var html = document.documentElement;
+            var currentIsEnglish = html.classList.contains('lang-en');
+            var newLang = currentIsEnglish ? 'de' : 'en';
+            html.classList.remove('lang-en', 'lang-de');
+            html.classList.add('lang-' + newLang);
+            html.lang = newLang;
+            localStorage.setItem('koala_lang', newLang);
+            var titles = { en: 'Join Room | KoalaSync', de: 'Raum beitreten | KoalaSync' };
+            document.title = titles[newLang] || titles.en;
+        }
+    </script>
 </head>
 <body>
    <div class="bg-blobs">
@@ -20,19 +45,22 @@
                <img src="assets/logo.png" alt="KoalaSync Logo">
                <span>KoalaSync</span>
            </a>
+            <button class="hamburger" onclick="document.querySelector('.nav-links').classList.toggle('open')" aria-label="Menu">☰</button>
            <div class="nav-links">
                <a href="index.html">Home</a>
                <a href="https://github.com/shik3i/KoalaSync" target="_blank">GitHub</a>
+                <a class="lang-toggle" onclick="toggleLanguage(event)">🌍 EN/DE</a>
            </div>
        </div>
    </nav>

    <main class="legal-content join-card">
        <div class="legal-card" id="join-container" data-reveal style="padding: 2.5rem;">
-            <div class="room-badge">INVITATION DETECTED</div>
-            <h1 id="join-title" style="font-size: 2rem; margin-bottom: 1rem;">Ready to sync?</h1>
+            <div class="room-badge"><span lang="en">INVITATION DETECTED</span><span lang="de">EINLADUNG ERKANNT</span></div>
+            <h1 id="join-title" style="font-size: 2rem; margin-bottom: 1rem;"><span lang="en">Ready to sync?</span><span lang="de">Bereit zum Synchronisieren?</span></h1>
            <p id="join-desc" style="text-align: center; color: var(--text-muted); margin-bottom: 2rem; font-size: 0.9rem;">
-                You've been invited to join a synchronized session.
+                <span lang="en">You've been invited to join a synchronized session.</span>
+                <span lang="de">Du wurdest eingeladen, einer synchronisierten Sitzung beizutreten.</span>
            </p>

            <div id="room-info-box" style="background: rgba(255,255,255,0.03); padding: 2rem; border-radius: 20px; margin-bottom: 2rem; border: 1px solid var(--glass-border); text-align: center; position: relative; overflow: hidden;">
@@ -41,7 +69,7 @@
            </div>

            <div id="join-actions" style="display: flex; flex-direction: column; gap: 1rem;">
-                <div style="text-align: center; color: var(--text-muted); font-size: 0.8rem;">Detecting extension...</div>
+                <div style="text-align: center; color: var(--text-muted); font-size: 0.8rem;"><span lang="en">Detecting extension...</span><span lang="de">Erweiterung wird erkannt...</span></div>
            </div>
        </div>
    </main>
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://sync.koalastuff.net/sitemap.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://sync.koalastuff.net/</loc>
+    <changefreq>monthly</changefreq>
+    <priority>1.0</priority>
+  </url>
+  <url>
+    <loc>https://sync.koalastuff.net/impressum.html</loc>
+    <changefreq>yearly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://sync.koalastuff.net/datenschutz.html</loc>
+    <changefreq>yearly</changefreq>
+    <priority>0.3</priority>
+  </url>
+</urlset>
@@ -176,13 +176,14 @@ nav {
    -webkit-text-fill-color: transparent;
 }

-.hero-text p {
+.hero-text p, .hero-subtitle {
    font-size: 1.5rem;
    color: var(--text-muted);
    margin-bottom: 3rem;
    max-width: 700px;
    margin-left: auto;
    margin-right: auto;
+    font-weight: 400;
 }

 .cta-group {
@@ -223,6 +224,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;
 }
@@ -383,11 +399,60 @@ footer {
    }
    .cta-group {
        justify-content: center;
+        flex-wrap: wrap;
    }
    .nav-links {
        display: none;
+        position: absolute;
+        top: 100%;
+        left: 0;
+        right: 0;
+        flex-direction: column;
+        background: rgba(15, 23, 42, 0.95);
+        backdrop-filter: blur(12px);
+        padding: 1rem 2rem;
+        gap: 1rem;
+        border-bottom: 1px solid var(--glass-border);
+    }
+    .nav-links.open {
+        display: flex;
+    }
+    .hamburger {
+        display: flex;
    }
    .legal-card {
        padding: 1.5rem;
    }
 }
+
+/* --- Language Toggle --- */
+html.lang-en [lang="de"],
+html.lang-de [lang="en"] {
+    display: none !important;
+}
+
+.lang-toggle {
+    cursor: pointer;
+    font-weight: 600;
+    user-select: none;
+    color: var(--text-muted);
+    transition: color 0.3s;
+}
+
+.lang-toggle:hover {
+    color: var(--accent);
+}
+
+/* --- Hamburger Menu --- */
+.hamburger {
+    display: none;
+    align-items: center;
+    justify-content: center;
+    background: none;
+    border: none;
+    color: var(--text);
+    font-size: 1.5rem;
+    cursor: pointer;
+    padding: 0.25rem;
+    line-height: 1;
+}
Author	SHA1	Message	Date
Timo	800a6c09b7	UI: Overwrite website logo/favicon with new monochrome icon	2026-05-18 14:58:18 +02:00
Timo	751496ed48	UI: Update KoalaSync icon to monochrome version to match neon theme	2026-05-18 14:56:22 +02:00
Timo	734a004f23	UI: Add new icon to popup header next to title	2026-05-18 14:52:06 +02:00
MacBook	01ce3ec99e	chore: migrate domains from shik3i.net to koalastuff.net	2026-05-16 13:08:53 +02:00
MacBook	d9b26f9fb4	docs: link Caddyfile.example and finalize website documentation	2026-05-04 05:55:46 +02:00
MacBook	1e3bb94660	website: fix HTML issues, mobile nav, i18n, and SEO Bug Fixes: - index.html: remove duplicate <title> tags (invalid HTML), use single title + JS swap; fix og:image relative→absolute URL (logo.png) - join.html: fix hardcoded lang=de, add language detection IIFE, add lang toggle to nav, make badge/title/desc/actions bilingual, add missing </head> closing tag, add noindex meta - app.js: join status handler was German-only; now fully bilingual (Success/Error titles, countdown, close/retry button labels) Improvements: - Add Firefox 'Add to Firefox' button to hero CTA (placeholder href=#) - impressum.html / datenschutz.html: add noindex meta to keep legal pages out of search results - robots.txt: add Sitemap directive for SEO crawlability - sitemap.xml: new file listing main page + legal pages with priorities - style.css: mobile nav hamburger menu (☰) replaces display:none blackout; nav-links drop down on mobile with backdrop blur - style.css: cta-group flex-wrap for narrow screens - Hamburger button added to all 4 page navs	2026-05-04 05:49:16 +02:00
MacBook	90882f91ef	docs: clarify ws:// vs wss:// for self-hosted servers	2026-05-04 05:42:31 +02:00
MacBook	5157428e74	docs: comprehensive repository polish + step-by-step user guide Documentation Rewrites: - AI_INIT.md: fix duplicate section numbers, add file responsibility map, fix stale manual mirror instruction, add room ID constraint - PRIVACY.md: add TL;DR statement, data retention table, explicit <all_urls> justification, self-hosted instance disclaimer - CONTRIBUTING.md: add local testing guide, version warning, room ID constraint, bug report requirements - shared/README.md: complete event table (all 15 events), fix stale manifest.json reference - docs/SYNC_GUIDE.md: Chrome→Browser, add README.md to sync list, drop stale RC5 reference - server/README.md: sync env defaults with .env.example (1000/50) New Documentation: - docs/HOW_IT_WORKS.md: 10-step walkthrough covering room creation, invitation bridge flow, synchronized playback, force sync protocol, heartbeat system, and episode auto-sync. Includes exact data payloads. Infrastructure Cleanup: - docker-compose.yml: remove deprecated version key - .dockerignore: remove dead .bat/.sh patterns - README.md: add self-hosting extension config tip, link HOW_IT_WORKS	2026-05-04 05:41:43 +02:00
MacBook	47ca7563b7	ci: auto-inject version from git tag + unify shared/ mirroring - CI release workflow now extracts version from tag (v1.4.0 → 1.4.0) and injects it into manifest.base.json, shared/constants.js, and package.json before building — the tag is the single source of truth - Build script now copies README.md alongside constants.js and blacklist.js from /shared → /extension/shared/ (full mirror) - .gitignore updated: extension/shared/ is fully generated by build - AI_INIT.md: simplified release workflow, fixed Chrome-only reference	2026-05-04 05:27:07 +02:00
MacBook	f7829bbebb	security: harden server relay + documentation audit Server Security (S-1 through S-8): - S-1: Type-check and clamp peerId, protocolVersion, password - S-2: Validate numeric/boolean/enum fields in relay peerData - S-3: Construct explicit relay payload (stop spreading raw data) - S-4: Type-check targetId and actionTimestamp in EVENT_ACK - S-5: Restrict room IDs to [a-zA-Z0-9-] only - S-7: Add eventCounts periodic cleanup alongside connectionCounts - S-8: Guard version parsing against NaN bypass Documentation (P-1, R-1 through R-6): - P-1: Fix PRIVACY.md typo, document all in-memory data maps - R-1/R-5: Fix stale sync-constants.bat references in shared/ - R-2: Fix stale lastTargetState ref in ARCHITECTURE.md - R-3: Extension README title reflects cross-browser support - R-6: Document content injection markers in scripts/README.md	2026-05-04 05:19:18 +02:00
MacBook	6093da4dc6	feat: add docker-compose example and update GHCR deployment links	2026-05-04 05:12:22 +02:00
MacBook	583e15745f	docs: improve transparency in privacy policy and readme	2026-05-04 04:55:04 +02:00
MacBook	bd8c7edc3a	docs: clean up README marketing language and remove banner	2026-05-04 04:51:29 +02:00
MacBook	bd4c53f9c7	docs: overhaul root README with premium branding and badges	2026-05-04 04:48:51 +02:00
MacBook	5440d136fe	docs: complete audit of all READMEs for consistency	2026-05-04 04:46:27 +02:00
MacBook	c9ec6ce3e0	docs: final polish and refined protocol automation	2026-05-04 04:45:02 +02:00
MacBook	652f1cef4f	refactor: automate protocol sync and reorganize repo for store readiness	2026-05-04 04:43:30 +02:00
MacBook	0f1f8bde1b	docs: clean up obsolete scripts and update documentation for store readiness	2026-05-04 04:37:59 +02:00
MacBook	fa4e4039b3	fix: bump APP_VERSION in shared/constants.js to 1.3.1	2026-05-02 02:09:23 +02:00
MacBook	cb466d3865	chore: bump version to 1.3.1 - update manifest.base.json, package.json and index.html to v1.3.1 - add SECURITY.md file	2026-05-02 02:07:22 +02:00
MacBook	54be9f9a39	feat: SEO and localization improvements - Add language toggle and German translation to website - Optimize manifest description - Add robots.txt - Add open source transparency clause to privacy policy	2026-05-02 02:00:06 +02:00
MacBook	47a9c08f48	docs: enforce strict version bumping in AI release workflow	2026-05-02 00:37:09 +02:00
MacBook	b0bcab77e3	docs: restructure README for end-users and developers, add browser support, add badges	2026-05-01 06:18:27 +02:00
MacBook	6624bcc1ca	docs: remove hardcoded version string and link to releases tab	2026-05-01 06:14:11 +02:00
MacBook	ca391ca83b	docs: add AI guardrails for networking, routing, and identity	2026-05-01 06:11:50 +02:00
MacBook	1438a4d41f	docs: add release tag 'v' prefix requirement to AI_INIT.md	2026-05-01 06:10:25 +02:00
MacBook	c9cf7c49dc	Fix logic flaws and update documentation	2026-05-01 06:06:46 +02:00
MacBook	bcbd46d658	fix: make shared file sync fail-fast in build script	2026-05-01 05:41:07 +02:00
MacBook	4d489ec992	chore: implement cross-browser build pipeline for extension - Extract manifest.json to manifest.base.json - Add Node.js build script to compile Chrome and Firefox artifacts - Remove legacy sync-constants bat/sh scripts - Update GitHub Actions workflow to use new build pipeline	2026-05-01 05:37:47 +02:00
Timo	65ad4b5c6b	chore: Bump version to 1.2.1 Patch release for: - fix: Seek relay filtering (HLS/DASH buffering micro-seeks no longer relayed) - feat: Seek diagnostic logging in Dev tab (Filtered/Relayed with delta) - feat: Log buffer increased from 50 to 200 entries	2026-04-25 17:47:59 +02:00
Timo	c2857dbdda	feat: Improve seek logging and increase log buffer to 200 entries - Log [Seek] Filtered when delta < 3s threshold (warn level) showing exact delta - Log [Seek] Relayed when a seek passes all filters (info level) showing target time + delta - Programmatic seeks (force sync, peer commands) remain silent in logs - Increase log ring buffer from 50 -> 200 entries in all three enforcement points	2026-04-25 17:45:06 +02:00
Timo	d07bf745a3	fix: Add seek delta threshold and debounce to prevent HLS/DASH buffering micro-seeks from being relayed as user seeks Streaming players (Emby, Jellyfin, etc.) perform frequent internal seeks for buffering that are < 1s in magnitude. These were being relayed to peers, causing brief video freezes every few minutes. Fix: - MIN_SEEK_DELTA = 3.0s: ignore seeks smaller than 3 seconds - 800ms debounce: settle rapid-fire seeks (e.g. scrubbing) before relaying - Programmatic seek suppression still takes priority via expectedEvents - lastReportedSeekTime baseline updated on programmatic seeks too	2026-04-25 17:42:55 +02:00
Timo	bd54e893b4	docs: Update root README for v1.2.0 features	2026-04-25 16:50:09 +02:00
Timo	50c9ba4ec8	docs: Update website for v1.2.0 release and add Episode Auto-Sync feature card	2026-04-25 16:49:52 +02:00
Timo	55c2d4ed0d	feat: Auto-Sync Next Episode v1.2.0 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	2026-04-25 16:43:10 +02:00
Timo	02afc193c6	fix: extend input sanitization to relay path and remove whitespace artefact	2026-04-25 16:17:16 +02:00
Timo	7fc156977a	feat: add graceful shutdown, input validation, and peer data factory (Phase 3)	2026-04-25 16:15:11 +02:00
Timo	99cb07bc2a	refactor: centralize room cleanup logic to fix DRY violation (H-1)	2026-04-25 16:12:51 +02:00
Timo	77ffda3e42	fix: address phase 1 audit findings (xss, cors, dead code)	2026-04-25 16:10:20 +02:00
Timo	01bc95e176	docs: add github link and version info to dev tab (v1.1.4)	2026-04-25 03:49:42 +02:00
Timo	7417c21217	feat: enhance peer list with volume icons, play/pause status, and time interpolation (v1.1.3)	2026-04-25 03:47:57 +02:00