Localize extension store metadata

The tab is still internally named data-tab="tab-dev". It used to be the
dev/diagnostics tab and was deliberately de-emphasized with font-size:
11px and a dimmer color. It was later relabelled to the user-facing
"Status" tab, but the rule stayed, leaving it 3px smaller and paler than
Room/Sync/Settings.

Drop tab-dev from the selector. #devToolsTabBtn, the opt-in Dev tab that
shares the rule, stays de-emphasized on purpose.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.dockerignore

@@ -7,7 +7,5 @@ extension/
 website/
 scripts/
 *.md
-*.bat
-*.sh
 .env
 server/.env

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# These are supported funding model platforms
+ko_fi: koaladev

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,56 @@
+---
+name: 🐛 Bug Report
+about: Create a report to help us improve KoalaSync
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+> **⚠️ Required:** Before submitting, open the KoalaSync **Status** tab in the extension popup and click **"Copy Logs"**. Paste the full output below — it contains essential system info, connection state, and debug data needed to diagnose your issue.
+
+<details>
+<summary><b>📋 Copy Logs Output</b></summary>
+
+<!-- Paste the copied logs here -->
+
+</details>
+
+---
+
+### Describe the Bug
+
+A clear and concise description of what the bug is.
+
+### To Reproduce
+
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+### Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+### Actual Behavior
+
+A clear and concise description of what actually happened.
+
+### Screenshots / Screen Recordings
+
+If applicable, add screenshots or recordings to help explain your problem.
+
+### Environment
+
+- **Browser:** (e.g. Chrome 125, Firefox 128)
+- **Extension Version:** (visible at the bottom of the Settings tab)
+- **OS:** (e.g. Windows 11, macOS 14.5)
+- **Self-Hosted Server?:** (yes / no — if yes, provide server version)
+- **Website/Platform:** (e.g. YouTube, Netflix, Twitch, Jellyfin, Emby)
+
+### Additional Context
+
+Add any other context about the problem here (e.g. network setup, VPN usage, multiple monitors, etc.).

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: 🚀 Feature Request
+about: Suggest a new feature or enhancement for KoalaSync
+title: ''
+labels: feature
+assignees: ''
+
+---
+
+### Problem Description
+
+A clear and concise description of the problem or limitation you're encountering. What's missing or what could be improved?
+
+*As a user, I want to ... so that ...*
+
+### Proposed Solution
+
+Describe the feature you'd like to see. How should it work? Be as specific as possible.
+
+### Use Cases & Benefits
+
+- **When would you use this?** (e.g., specific websites, workflows, setups)
+- **What value does it add?** (e.g., saves time, enables new functionality, improves UX)
+
+### Alternatives Considered
+
+What workarounds or alternative approaches have you tried? Are there other ways to achieve a similar result?
+
+### Additional Context
+
+Add any other context, sketches, mockups, or references (e.g., links to similar features in other projects).

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+<!--
+Thanks for contributing to KoalaSync!
+
+Please read the CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting.
+By submitting this PR, you agree to abide by our code of conduct.
+
+Use conventional commits for the title: feat:, fix:, docs:, refactor:, chore:
+-->
+
+### Description
+
+<!-- What does this PR do and why? Link to relevant issue or motivation. -->
+
+Closes #
+
+### Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that alters existing behavior)
+- [ ] Refactoring (no functional changes)
+- [ ] Documentation update
+- [ ] Build, dependencies, or CI
+
+### How Has This Been Tested?
+
+<!-- Describe the tests you ran and the environments (browsers, OS, etc.) -->
+
+- [ ] Tested on Chrome
+- [ ] Tested on Firefox
+- [ ] `npm run lint` passes with zero errors and zero warnings
+- [ ] `node -c` passes on all modified `.js` files
+
+### Checklist
+
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my code
+- [ ] I have added/updated tests if needed
+- [ ] I have updated documentation if needed (`docs/`, README, etc.)
+- [ ] Protocol changes: I ran `node scripts/build-extension.cjs` and updated relevant docs
+- [ ] No new warnings, secrets, or hardcoded credentials introduced
+
+### Additional Context
+
+<!-- Screenshots, migration notes, performance data, etc. -->

.github/workflows/beta-server-image.yml

@@ -0,0 +1,75 @@
+name: Beta Server Image
+
+# Publishes the relay server as a Docker image under NON-production tags so a
+# feature branch can be deployed to a staging/backup server and used as a custom
+# server, without ever touching the ':latest' tag the official relay tracks.
+#
+# Tags produced (on ghcr.io/<owner>/<repo>):
+#   - beta                         moving channel pointer to the newest build
+#   - <branch-slug>                e.g. feature-host-control-mode
+#   - sha-<short-commit>           immutable, pin to an exact build
+#   - <custom>                     only on manual run, e.g. hostcontrol01
+# Never ':latest' (flavor: latest=false).
+#
+# Remove this workflow once the feature is merged & released the normal way.
+
+on:
+  push:
+    branches:
+      - feature/host-control-mode
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Extra immutable tag for this build (e.g. hostcontrol01). Optional.'
+        required: false
+        default: ''
+
+concurrency:
+  group: beta-image-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-beta-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          # Never publish ':latest' from a beta build.
+          flavor: |
+            latest=false
+          tags: |
+            type=raw,value=beta
+            type=ref,event=branch
+            type=sha,prefix=sha-
+            type=raw,value=${{ github.event.inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag != '' }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: server/Dockerfile
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+# Runs the full verification suite (lint, unit/integration tests, production
+# audits, extension + website build) on every push to main and every PR, so a
+# regression can never reach main or a release tag unchecked.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+# Cancel superseded runs on the same ref to save CI minutes. Unlike the release
+# workflow, an interrupted CI run has no side effects.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+            server/package-lock.json
+
+      - name: Install root dependencies
+        run: npm ci
+
+      # The server test suite (test-server-ws/routes/ops) imports express,
+      # socket.io, and dotenv from server/node_modules, so install them too.
+      - name: Install server dependencies
+        run: npm ci
+        working-directory: server
+
+      - name: Run verification suite
+        run: npm run verify

.github/workflows/release.yml

@@ -5,21 +5,29 @@ on:
     tags:
       - 'v*'
 
+# A release run must never be interrupted (it commits back to main and publishes
+# artifacts). Only dedupe accidental re-pushes of the same tag.
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
 jobs:
   release-server:
     runs-on: ubuntu-latest
     permissions:
-      contents: write
+      contents: read
       packages: write
+      id-token: write
+      attestations: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -27,7 +35,7 @@ jobs:
 
       - name: Extract Docker metadata
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
@@ -35,35 +43,115 @@ jobs:
             type=ref,event=tag
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v5
+        id: build
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: server/Dockerfile
           push: true
+          platforms: linux/amd64,linux/arm64
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          # Reuse layers across releases to speed up the multi-arch build.
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Generate artifact attestation
+        uses: actions/attest@v4
+        with:
+          subject-name: ghcr.io/${{ github.repository }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true
 
   release-extension:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      id-token: write
+      attestations: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
-      - name: Sync Protocol Constants
-        run: |
-          chmod +x ./scripts/sync-constants.sh
-          ./scripts/sync-constants.sh
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'
 
-      - name: Create Extension Zip
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Inject version into source files
         run: |
-          zip -r koala-sync-extension.zip extension/ -x "*.DS_Store*"
+          VERSION=${{ steps.version.outputs.VERSION }}
+          DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          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"
+
+          # 4. website/version.json
+          jq -n --arg v "$VERSION" --arg d "$DATE" '{version: $v, date: $d}' > website/version.json
+          echo "  ✓ website/version.json -> version $VERSION, date $DATE"
+
+          # 5. website/template.html — SoftwareApplication schema
+          sed -i "s/\"softwareVersion\": \".*\"/\"softwareVersion\": \"$VERSION\"/" website/template.html
+          echo "  ✓ website/template.html -> softwareVersion $VERSION"
+
+          # 6. README.md — version badge & banner
+          sed -i "s|Release-v[0-9]\+\.[0-9]\+\.[0-9]\+-blue|Release-v$VERSION-blue|g" README.md
+          sed -i "s/New v[0-9]\+\.[0-9]\+\.[0-9]\+ Release/New v$VERSION Release/g" README.md
+          echo "  ✓ README.md -> v$VERSION"
+
+          echo "Version injection complete."
+
+      - name: Commit and push version updates back to main
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add extension/manifest.base.json shared/constants.js package.json website/version.json website/template.html README.md
+          git commit -m "chore(release): update versions to $GITHUB_REF_NAME [skip ci]" || echo "No changes to commit"
+          git push origin HEAD:main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build Extensions
+        run: |
+          npm ci
+          npm run build:extension
+
+      - name: Generate artifact attestation for extensions
+        uses: actions/attest@v4
+        with:
+          subject-path: dist/koalasync-*.zip
+
+      - name: Build Website
+        run: node website/build.cjs
+
+      - name: Upload Website Artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: website-www
+          path: website/www/
+          if-no-files-found: error
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v3
         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

.gitignore

@@ -27,6 +27,7 @@ Thumbs.db
 # IDEs
 .vscode/
 .idea/
+.claude/
 *.swp
 *.swo
 
@@ -40,5 +41,24 @@ coverage/
 # the root 'shared/' remains the Single Source of Truth.
 extension/shared/
 
+# Auto-generated website build output
+website/www/
+website/.avif-cache.json
+
 # Temporary scratch files
 scratch/
+
+# AI Assistants and Agents
+.agents/
+.antigravity/
+.gemini/
+.claude/
+.codex/
+.opencode/
+.cursor/
+.cursorrules
+.copilot/
+.cline/
+.clinerules
+.windsurfrules
+.codeium/

AI_INIT.md

@@ -1,98 +0,0 @@
-# KoalaSync AI Onboarding (AI_INIT.md)
-
-Welcome to the KoalaSync project. This file is the primary entry point for any developer or AI agent working on this codebase. It defines the architecture, non-negotiables, and workflows required to maintain the stability and security of the system.
-
-> [!IMPORTANT]
-> **Privacy & Data Sovereignty**: KoalaSync follows a strict **Zero-External-Requests Policy**: The extension and website must not make requests to any third-party domains (Google Fonts, CDNs, etc.). All assets (fonts, icons, scripts) must be self-hosted or use system defaults.
-> - **Font Stack**: Use a modern system font stack (e.g., -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif) to maintain a premium look without external dependencies. Prohibit the use of `@import` or `<link>` for external font services.
-
----
-
-## 1. Project Overview
-KoalaSync is a specialized tool for **synchronized video playback** across multiple remote peers. It supports YouTube, Twitch, and native HTML5 video elements. 
-- **Users**: Friends or groups wanting to watch synchronized content together.
-- **Workflow**: A user creates a room, shares an invitation link, and all peers in that room are synchronized via a Node.js relay server.
-- **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.
-- `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`).
-- `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`. 
-> - **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.
-
-## 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.
-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.
-
-## 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.
-
-## 5. 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`.
-- **Tab Structure**: Must maintain the **Room**, **Sync**, **Settings**, and **Dev** tabs.
-- **CSS Variables**:
-  | Variable | Value | Purpose |
-  | :--- | :--- | :--- |
-  | `--bg` | `#0f172a` | Main background |
-  | `--card` | `#1e293b` | Form and info cards |
-  | `--accent` | `#6366f1` | Primary actions and branding |
-  | `--success` | `#22c55e` | Success states / Online dot |
-  | `--error` | `#ef4444` | Errors / Offline dot |
-
-## 5. 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.
-- **Dual Heartbeat**: 
-    - **Background Heartbeat (30s)**: Ensures session persistence even without a video element.
-    - **Content Heartbeat (15s)**: Transmits current video metadata (time, title).
-- **Dead Peer Pruning**: Server "Reaper" disconnects peers after 5 minutes of total silence (no heartbeats or events).
-- **Deduplication**: Server kills old sockets if a user re-joins with the same `peerId` to prevent ghosts.
-- **Platform Specifics**: Specialized click-logic for YouTube (`.ytp-play-button`) and Twitch.
-- **pollSeekReady()**: Polling mechanism that checks `video.readyState` before acknowledging sync.
-- **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.
-
-## 6. 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.
-- **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
-- **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
-
-### 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`).
-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.
-
-### Locking Old Versions
-1. Increase `APP_VERSION` in `shared/constants.js`.
-2. Update `MIN_VERSION` in the server's `.env` file and restart.

ARCHITECTURE.md

@@ -1,49 +0,0 @@
-# KoalaSync Architecture
-
-This document describes the communication flows and internal logic of the KoalaSync system.
-
-## 1. Extension Startup & Connection
-- **Initialization**: On startup, `background.js` reads settings (Server URL, Username, Last Room) from `chrome.storage.sync`.
-- **WebSocket Handshake**:
-  1. Background creates a `new WebSocket` to `/socket.io/?EIO=4&transport=websocket&version=1.0.0`.
-  2. Server performs security checks:
-     - **IP Rate Limit**: Checks if the IP has exceeded connection limits.
-     - **Protocol Version**: Client must match the server's protocol (currently `1.0.0`).
-  3. Server responds with Engine.IO handshake (`0`) and the client joins the namespace (`40`).
-- **Room Join**: Background emits `JOIN_ROOM` containing `roomId`, `password`, `peerId`, and `username`.
-- **Deduplication**: If a user joins with a `peerId` that already has an active socket, the server kills the old socket to prevent "Ghost Peers".
-
-## 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.
-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`.
-
-## 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`.
-4. **Resume**: All peers call `play()` simultaneously.
-
-## 4. 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
-- **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
-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).

CODE_OF_CONDUCT.md

@@ -0,0 +1,131 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at **koalasync@koalastuff.net**.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All project maintainers are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Project maintainers will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from project maintainers, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,168 @@
+# Contributing to KoalaSync
+
+Thanks for your interest in improving KoalaSync. All contributions are welcome — from bug reports and translations to core protocol changes.
+
+Please note that by participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## Ways to Contribute
+
+| Area | Description |
+|------|-------------|
+| **Bug Reports** | Found a bug? Open an issue with repro steps (see template below). |
+| **Code** | Fix bugs, add features, or improve the extension / server / website. |
+| **Translations** | Help localize the extension and website into more languages. See [TRANSLATION.md](docs/TRANSLATION.md). |
+| **Documentation** | Improve docs, fix typos, or add missing examples. |
+| **Security** | Found a vulnerability? See [SECURITY.md](SECURITY.md) — do NOT open a public issue. |
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** v18+
+- **Docker** (for local relay server testing)
+
+### Quick Start
+
+```bash
+git clone https://github.com/Shik3i/KoalaSync.git
+cd KoalaSync
+npm install
+node scripts/build-extension.cjs
+```
+
+---
+
+## Project Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| `extension/` | Browser extension (Manifest V3, Chrome & Firefox) |
+| `server/` | Node.js + Socket.IO relay server (Dockerized) |
+| `website/` | Landing page, invitation bridge, and marketing site |
+| `shared/` | Protocol constants — single source of truth |
+| `scripts/` | Build and sync utilities |
+| `docs/` | Architecture, sync protocol, and deep-dive guides |
+
+---
+
+## Testing Locally
+
+### Extension
+
+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 sync.
+5. Use the extension's **Dev tab** to inspect real-time video element state (`readyState`, `currentTime`, `paused`).
+
+### Website
+
+```bash
+node website/build.cjs           # Compile static site → www/
+python3 -m http.server 8080 -d website/www  # Serve locally
+```
+
+Then open `http://localhost:8080`. For multi-language testing: `http://localhost:8080/de/`.
+
+---
+
+## Protocol Constants
+
+KoalaSync uses a **single source of truth** for all protocol constants in `shared/constants.js`.
+
+> [!IMPORTANT]
+> After modifying `shared/constants.js`, you **must** run the build script to sync changes to the extension:
+> ```bash
+> node scripts/build-extension.cjs
+> ```
+> This automatically injects constants into `content.js` and regenerates browser bundles in `dist/`.
+
+---
+
+## Code Standards
+
+- **Vanilla JS**: The extension must remain dependency-free. No npm packages in `extension/`.
+- **Privacy-first**: Zero external requests — no CDNs, fonts, analytics, or trackers. All assets self-hosted.
+- **System font stack**: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, ...` — never `@import` external fonts.
+- **Room IDs**: Restricted to `[a-zA-Z0-9-]` (alphanumeric + hyphens only). Enforced server-side.
+- **Comments**: Document complex sync logic. The codebase uses inline comments for protocol reasoning.
+
+---
+
+## Version Numbers
+
+> [!CAUTION]
+> **Never manually bump version numbers.** The CI pipeline injects the version from the git tag into `manifest.base.json`, `shared/constants.js`, and `package.json` during release builds. Manual bumps cause conflicts.
+
+---
+
+## Open Source Workflow & Pull Requests
+
+If you are new to open-source contributions, follow these steps to propose your changes:
+
+1. **Fork the Repository**: Click the "Fork" button at the top right of this repository to create your own copy of KoalaSync.
+2. **Clone your Fork**: `git clone https://github.com/YOUR-USERNAME/KoalaSync.git`
+3. **Create a Branch**: `git checkout -b my-new-feature` (e.g. `feature/dark-mode` or `fix/translation-de`)
+4. **Make your Changes**: Edit the files, then verify them locally.
+   - *Extension/Server changes*: Test on Chrome/Firefox and check `npm run lint`.
+   - *Website/Translation changes*: Run `node website/build.cjs` and check the output in `www/`.
+5. **Commit and Push**: `git commit -m "Add my feature"` and `git push origin my-new-feature`
+6. **Open a Pull Request (PR)**: Go to the original KoalaSync repository on GitHub and click "New Pull Request".
+
+### PR Code Requirements
+- **Lint**: Ensure `npm run lint` passes with zero errors and warnings.
+- **Syntax**: Run `node -c` on every modified `.js` file.
+- **Protocol changes**: Update relevant documentation in `docs/`.
+
+---
+
+## Bug Report Template
+
+When filing a bug, the easiest way is to use the **Copy Logs** button in the extension's **Status** tab. It copies a fully formatted Markdown report to your clipboard containing:
+
+- System info (version, protocol, peer ID, browser)
+- Connection status (server, room, peers, reconnect state)
+- Video debug info (playback state, readyState, network state, dimensions, error codes, shadow DOM detection, platform)
+- Action history (last 20 events)
+- Log entries (last 50)
+
+Simply paste the clipboard contents into your GitHub issue and add:
+
+| Field | Example |
+|-------|---------|
+| **Steps to Reproduce** | 1. Create room → 2. Join from second browser → 3. Play video |
+| **Expected Behavior** | Both peers play simultaneously |
+| **Actual Behavior** | Peer B remains paused |
+
+If you cannot access the Status tab, include as much of the following manually:
+
+| Field | Example |
+|-------|---------|
+| **Browser** | Chrome 125, Firefox 128 |
+| **Extension Version** | v1.9.3 (visible at bottom of Settings tab) |
+| **Website/Platform** | Netflix, YouTube, Twitch, Jellyfin, etc.
+
+---
+
+## Translation Contributions (Translators Welcome!)
+
+We welcome native speakers to help translate KoalaSync! You **do not** need deep programming knowledge to contribute translations.
+
+KoalaSync supports multiple languages. To add or improve translations:
+1. Read the **[Translation Guide](docs/TRANSLATION.md)** first. It explains how our localization system works.
+2. Edit the `.json` files in `website/locales/` (for the website) and `extension/locales/` (for the extension).
+3. Test your translations locally by running:
+   - `node scripts/test-locales.cjs` (for extension)
+   - `node scripts/test-website-locales.mjs` (for website)
+   - `node website/build.cjs` (to build the site)
+4. Follow the **Open Source Workflow** above (Fork -> Branch -> Edit -> PR) to submit your translations.
+
+---
+
+## Security
+
+If you discover a security vulnerability, **do not open a public issue**. Report it privately as described in [SECURITY.md](SECURITY.md).

README.md

@@ -1,69 +1,152 @@
-# KoalaSync
+<p align="center">
+  <img src="website/assets/PlatformJuggler_New.webp" width="280" alt="KoalaSync Mascot">
+</p>
 
-KoalaSync is a premium, lightweight Chrome Extension and Relay Server for synchronized video playback across any website (YouTube, Twitch, Netflix, and custom HTML5 players).
+<h1 align="center">KoalaSync</h1>
 
-> [!TIP]
-> **New Developers & AI Agents**: Please read [AI_INIT.md](AI_INIT.md) before starting work.
+<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/badge/Release-v2.6.3-blue?logo=github" alt="GitHub release"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License"></a>
+  <a href="https://addons.mozilla.org/de/firefox/addon/koalasync/"><img src="https://img.shields.io/badge/Firefox-Download-orange?logo=firefoxbrowser&logoColor=white" alt="Firefox Add-on"></a>
+  <a href="https://chromewebstore.google.com/detail/koalasync/obbnmkmlaaddodakcbdljknjpagklifc"><img src="https://img.shields.io/badge/Chrome-Download-blue?logo=googlechrome&logoColor=white" alt="Chrome Extension"></a>
+</p>
 
-## 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.
+<p align="center"><i>KoalaSync is a lightweight Browser Extension and Relay Server for synchronized video playback on almost any website with a video element—YouTube, Twitch, Netflix, Emby, Jellyfin, and beyond. Built with a focus on <b>Data Sovereignty</b> and <b>Performance</b>.</i></p>
 
-> [!NOTE]
-> For deep technical dives, see [ARCHITECTURE.md](ARCHITECTURE.md) and [SYNC_GUIDE.md](SYNC_GUIDE.md).
+<p align="center"><a href="docs/CHANGELOG.md"><b>New v2.6.3 Release!</b> — See what's changed</a></p>
+
+### 🌟 Why KoalaSync?
+
+*   **🛡️ Security-First**: Volatile RAM-based relay with built-in brute-force protection and zero-persistence architecture. We keep no logs of your sessions or synchronizations. *We don't track you. We only track our server* (relying on the [aggregated, anonymous, non-personal metrics](https://syncserver.koalastuff.net/health) provided under `/health`).
+*   **📡 Direct Logic**: Manual Socket.IO wire implementation for reliable 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.
+- **Host Control & Co-Hosts**: Room hosts can lock playback control to trusted controllers while guests keep watching in sync.
+- **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.
+- **Efficient Relay**: Minimal overhead WebSocket message forwarding.
+- **Seamless Invitations**: Smart links that automatically configure server and room credentials for your friends.
+- **Smart Audio Compressor**: Tired of constantly riding the volume? Automatically balance out whispering dialogue and deafening explosions with simple presets, or fully customize the audio to your liking.
 
-## Setup Instructions
+---
 
-### 1. Relay Server (Docker)
-The server runs on Node.js using Socket.IO, containerized for easy deployment.
+### 🚀 Quick Start
 
+#### For Users (Installation & Usage)
+The easiest and safest way to install KoalaSync is directly through the official browser stores:
+
+<p>
+  <a href="https://chromewebstore.google.com/detail/koalasync/obbnmkmlaaddodakcbdljknjpagklifc"><img src="https://img.shields.io/badge/Chrome-Download-blue?logo=googlechrome&logoColor=white&style=for-the-badge" alt="Chrome Extension"></a>
+  <a href="https://addons.mozilla.org/de/firefox/addon/koalasync/"><img src="https://img.shields.io/badge/Firefox-Download-orange?logo=firefoxbrowser&logoColor=white&style=for-the-badge" alt="Firefox Add-on"></a>
+</p>
+
+*(For manual offline installation: Download the latest `.zip` from the [Releases](https://github.com/Shik3i/KoalaSync/releases) page and load it as an "Unpacked Extension" in Developer Mode).*
+
+**How to use:**
+1. **Create a Room:** Click the Koala icon in your browser and hit `+ Create New Room`.
+2. **Invite Friends:** Share the auto-copied invite link. Once they click it, they automatically join.
+3. **Pick a Video:** Navigate to the Sync Tab, select the tab playing your video, and grab some popcorn! 🍿
+
+---
+
+### 🌐 Localization & Translations
+
+Both the official KoalaSync website and the browser extension feature dynamic localization:
+- **Available Languages**: Support is included for 15 languages: English (`en`), German (`de`), French (`fr`), Spanish (`es`), Portuguese (Brazil) (`pt-BR`), Russian (`ru`), Italian (`it`), Polish (`pl`), Turkish (`tr`), Dutch (`nl`), Japanese (`ja`), Korean (`ko`), Chinese (Simplified) (`zh`), Ukrainian (`uk`), and European Portuguese (`pt`).
+- **Real-Time Extension Localization**: Inside the extension Settings panel, users can swap languages instantly. The entire interface, notifications, Empty States, and onboarding guides re-translate dynamically in real-time.
+- **Contributing**: We welcome community translations for both the website and the extension! Please refer directly to the [TRANSLATION.md](docs/TRANSLATION.md) guide for step-by-step instructions on how to audit, refine, or add new languages.
+
+
+---
+
+### 🛠️ For Developers & Self-Hosters
+
+#### 📂 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)).
+
+#### Building from Source
+To build the extension from source and synchronize protocol constants:
 ```bash
-# From the root directory
-docker-compose up -d --build
+npm install
+npm run build:extension
 ```
-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)
+For local development or a simple private relay, use the root Compose file:
+```bash
+cp server/.env.example server/.env
+# Edit server/.env and set SERVER_SALT to a unique random value:
+# openssl rand -base64 32
+docker compose up -d --build
+```
+The local relay will be available at `ws://localhost:3000`.
 
-## 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.
+For production, use the official image and one of the ready-to-edit examples:
+- [Docker network compose](examples/docker-compose.caddy.example.yml): for a Caddy or reverse-proxy network. This file does not publish `localhost:3000`; Caddy routes traffic to the container.
+- [Static IP compose](examples/docker-compose.ip.example.yml): for a pre-existing Docker network with a fixed container IP.
 
-## 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.
+In every real deployment, set a unique `SERVER_SALT`. Without it the relay still starts, but it warns that room-password hashes are using the public fallback salt from the repository.
 
-## 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.
+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`).
 
-## 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).
+> **⚠️ 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](examples/Caddyfile.example) for a production-ready template.
+
+To verify your relay is reachable from outside, visit `https://your-domain.com` in a browser — it should return `{"status":"online","service":"KoalaSync Relay"}`.
+
+#### Supply Chain Security (v2.2.2+)
+
+All official release artifacts (Docker images and extension binaries) are published with signed [artifact attestations](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations) to prove they were built from this repository's source code.
+
+**Verify a Docker image:**
+```bash
+gh attestation verify oci://ghcr.io/shik3i/koalasync:latest \
+  -R Shik3i/KoalaSync
+```
+
+**Verify an extension binary:**
+```bash
+gh attestation verify dist/koalasync-chrome.zip \
+  -R Shik3i/KoalaSync
+```
+
+---
+
+### 📖 Documentation & Links
+
+- **[CHANGELOG.md](docs/CHANGELOG.md)**: Full version history for the extension and relay server.
+- **[TESTED_SERVICES.md](docs/TESTED_SERVICES.md)**: Detailed compatibility matrix of tested streaming platforms and known limitations.
+- **[TRANSLATION.md](docs/TRANSLATION.md)**: Translation and localization guide for contributors.
+- **[PRIVACY.md](docs/PRIVACY.md)**: Data Handling and Privacy Policy.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)**: How to help make KoalaSync better.
+- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)**: Our community standards and expectations.
+- **[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.
+- **[PROTOCOL.md](docs/PROTOCOL.md)**: WebSocket protocol specification and event reference.
+- **[ROADMAP.md](docs/ROADMAP.md)**: Planned features, backlog, and rejected ideas.
+- **[SECURITY.md](SECURITY.md)**: Disclosure policy and security practices.
+- **[AI_INIT.md](docs/AI_INIT.md)**: Maintainer and agent onboarding notes for safe code changes.
+- **[Caddyfile.example](examples/Caddyfile.example)**: Production Caddy configuration for website and relay.
+
+---
+
+<div align="center">
+  <sub><a href="https://support.koalastuff.net"><img src="https://img.shields.io/badge/Support-KoalaSync-FF5E5B" alt="Support KoalaSync"></a></sub>
+  <sub><a href="https://gitgem.org/github/Shik3i/KoalaSync"><img src="https://gitgem.org/api/badge/github/Shik3i/KoalaSync.svg" alt="GitGem Badge" /></a></sub>
+
+  <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>

SECURITY.md

@@ -0,0 +1,102 @@
+# Security Policy
+
+KoalaSync is built on a **zero-persistence, privacy-first** architecture. We take security seriously and appreciate responsible disclosure of vulnerabilities.
+
+---
+
+## Supported Versions
+
+Only the latest stable release receives security patches.
+
+| Version | Supported |
+|---------|-----------|
+| Latest release | :white_check_mark: Active |
+| Older versions | :x: Unsupported |
+
+Users on older versions are encouraged to update. The server enforces a minimum client version via `MIN_VERSION`.
+
+---
+
+## Scope
+
+The following components are within scope for security reports:
+
+| Component | Examples |
+|-----------|----------|
+| **Relay Server** (`server/`) | Authentication bypass, rate-limit evasion, room hijacking, DoS vectors |
+| **Browser Extension** (`extension/`) | XSS via content scripts, privilege escalation, data exfiltration, tab snooping |
+| **WebSocket Protocol** | Message injection, replay attacks, man-in-the-middle (WSS bypass) |
+| **Website** (`website/`) | XSS, CSP bypass, invitation-hash leaks |
+
+### Out of Scope
+
+- Theoretical attacks requiring physical device access
+- Social engineering or phishing
+- Denial of service via resource exhaustion on self-hosted instances
+- Vulnerabilities in third-party browser extensions or websites
+
+---
+
+## Reporting a Vulnerability
+
+> [!CAUTION]
+> **Do NOT open a public GitHub issue for security vulnerabilities.** Public disclosure before a patch is available puts users at risk.
+
+Instead, email the project maintainer privately:
+
+**`koalasync@koalastuff.net`**
+
+Encrypt sensitive findings with our PGP key (available on request).
+
+### What to Include
+
+- **Affected component**: Server / Extension / Website / Protocol
+- **Steps to reproduce**: Clear, minimal steps to trigger the vulnerability
+- **Impact**: What an attacker could achieve (data access, privilege escalation, etc.)
+- **Environment**: Browser version, extension version, server configuration
+- **Suggested fix** (optional): If you have ideas for a patch
+
+### What to Expect
+
+| Timeline | Action |
+|----------|--------|
+| **Within 48 hours** | Acknowledgment of your report |
+| **Within 7 days** | Initial assessment and severity confirmation |
+| **As needed** | Collaborative discussion for clarification |
+| **After patch** | Notification that the fix is deployed |
+| **After rollout** | Public acknowledgment in release notes (or anonymity if preferred) |
+
+---
+
+## Architecture & Threat Model
+
+KoalaSync's security is grounded in its architecture:
+
+- **RAM-only relay**: No database, no persistent logs. All session data evaporates on disconnect.
+- **Keyed SHA-256 room password hashes**: Plaintext passwords are never stored. Room passwords are held only as in-memory HMAC-SHA256 hashes for the short room lifetime, with brute-force protection: 5 attempts → 15-minute IP lockout.
+- **Rate limiting**: Connection rate (IP-based, 60s window), health endpoint rate (10 requests/minute/IP), wrong admin-metrics bearer attempts (5 requests/minute/IP), and event rate (per-socket, 10s window). Health-style JSON responses are cached server-side for 60 seconds and refreshed lazily on request.
+- **Reverse proxy boundary**: The relay trusts one proxy hop for client IP detection. In production, keep the Node server reachable only through Caddy or another trusted reverse proxy.
+- **URL-hash credential isolation**: Invitation credentials live in the URL fragment (`#join:...`) — never sent to the web server.
+- **Strict CSP**: `default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'`.
+- **No third-party requests**: Zero CDNs, fonts, analytics, or external scripts.
+
+If you find a way to bypass any of these protections, we want to know about it.
+
+> [!NOTE]
+> Some frequently-reported "issues" are **intentional and out of scope** for our
+> threat model (ephemeral, account-less rooms of invited participants) — e.g. an
+> unauthenticated `peerId` or non-constant-time room-password compare. Before
+> reporting, please read **[`docs/KNOWN_LIMITATIONS.md`](docs/KNOWN_LIMITATIONS.md)**.
+
+---
+
+## Responsible Disclosure
+
+We follow the principle of **coordinated vulnerability disclosure**:
+
+1. You report privately.
+2. We investigate and develop a patch.
+3. We deploy to the Chrome Web Store, Firefox Add-ons, and Docker registry.
+4. We credit you publicly (unless you prefer to remain anonymous).
+
+We do not pursue legal action against researchers who act in good faith and follow this disclosure process.

SYNC_GUIDE.md

@@ -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.

assets/MarketingCopy.md

@@ -0,0 +1,66 @@
+# KoalaSync — Marketing Copy Kit
+
+Ready-to-paste copy for product listings, launch pages, directory submissions, and anywhere else you keep re-typing the same pitch. Three lengths, one consistent message. Pick the one that fits the field limit.
+
+---
+
+## 1. One-Sentence Pitch
+
+> KoalaSync is a privacy-first browser extension that synchronizes video playback across almost any website so you can watch with friends in real time — no accounts, no tracking, and your video never passes through anyone's server but the original site's.
+
+**Shorter alternative** (for tight tagline fields):
+
+> Private, universal watch parties on any website — no accounts, no tracking, no media proxying.
+
+---
+
+## 2. Three-Sentence Overview
+
+> KoalaSync is a lightweight browser extension that keeps you and your friends perfectly in sync on YouTube, Netflix, Twitch, Prime Video, Jellyfin, Emby, and almost any other site with an HTML5 video player — press play once and everyone stays together. It's built privacy-first: no accounts, no telemetry, and the official relay server runs entirely in volatile RAM with zero persistence, so nothing about your sessions is ever stored. Open source under the MIT license and fully self-hostable with a single Docker Compose command, KoalaSync is a transparent watch-party tool that works everywhere and respects your data sovereignty.
+
+---
+
+## 3. Full Description
+
+### Watch together — on any site, on your terms.
+
+Counting down "3, 2, 1, play" over voice chat doesn't scale past two people. KoalaSync fixes that with a tiny browser extension that synchronizes play, pause, and seeking across everyone in the room, on almost any website with a `<video>` element. Create a room, share a link, press play — that's it.
+
+### What makes KoalaSync different
+
+Most watch-party tools fall into one of two traps: they only work on a short allowlist of sites (site-specific extensions that need a separate build for every platform), or they route your video through their own player and servers. KoalaSync was built around three principles that break that mold.
+
+**Universal by design.** If the site has an HTML5 `<video>` element, KoalaSync can usually sync it. YouTube, Netflix, Twitch, Prime Video, Disney+, Jellyfin, Emby, and countless niche sites work out of the box — no per-site integration to wait for, no extension swap when your friends want to switch services.
+
+**Your video never touches our servers.** KoalaSync only relays tiny timing messages — play, pause, seek position, readiness — over a hand-rolled WebSocket protocol. The actual video keeps streaming directly from the original site to each viewer's browser. KoalaSync never proxies, transcodes, uploads, or redistributes a single frame, which also means there is no legal gray zone around redistribution.
+
+**Privacy is the default, not an upgrade.** No accounts, no emails, no telemetry, no analytics, no behavior profiling. The official relay server runs entirely in volatile RAM and keeps zero persistent state — when the room closes, the data is gone. Pick a nickname or let KoalaSync generate one for you and you're in.
+
+### Built for people who actually want to read the code
+
+KoalaSync is MIT-licensed open source, built by a solo developer. Audit it, fork it, change it. The extension is dependency-free with a direct Socket.IO wire implementation — no opaque libraries, no framework bloat, no surprise third-party SDKs. Want full sovereignty? Set a unique `SERVER_SALT` in the supplied Compose file, then start your own relay with a single Docker Compose command and keep all watch-party coordination traffic inside your own infrastructure. The official public relay is there when you don't care, self-hosting is there when you do.
+
+### Little touches you'll notice
+
+- **Episode Auto-Sync** pauses the room when someone loads the next episode and resumes only when everyone is ready — no spoilers, no one left behind on the previous cliffhanger.
+- **Smart Audio Compressor** tames the modern "whisper dialogue, deafening explosion" mix with one click. Three presets or full manual control over threshold, ratio, attack, and release.
+- **One-click invite links** auto-configure the server and room for your friends — they just click the link and they're in. No fumbling with server URLs or room IDs.
+- **Dual-heartbeat architecture** kills ghost rooms and stale connections before they desync your session.
+- **15 languages** fully translated and switchable in real time from the settings panel — English, German, French, Spanish, Portuguese (Brazil + European), Russian, Italian, Polish, Turkish, Dutch, Japanese, Korean, Chinese, Ukrainian.
+
+### Install and start in under a minute
+
+Install KoalaSync from the Chrome Web Store or Firefox Add-ons, click "Create Room," share the invite link, and pick a video. The official relay is ready out of the box — no setup required unless you want to self-host.
+
+- Website: https://sync.koalastuff.net
+- GitHub: https://github.com/Shik3i/KoalaSync
+
+---
+
+## Bonus: Taglines (for hero headlines, social bios, meta descriptions)
+
+- Watch together. Anywhere. Privately.
+- The watch-party tool that works on every site and tracks none of them.
+- Sync play, pause, and seek on any video — no accounts, no logs, no lock-in.
+- Self-hostable, open-source watch parties for the post-"3, 2, 1, play" era.
+- Press play once. Stay together anywhere.

assets/StoreAssets/StoreDescription.md

@@ -0,0 +1,57 @@
+KoalaSync: Private Watch Parties for Emby, Jellyfin, Plex, Netflix & YouTube
+
+Tired of counting down "3, 2, 1, Play" over voice chat? KoalaSync keeps you and your friends perfectly in sync. Whether you are streaming from your own self-hosted media server like Emby, Jellyfin or Plex, or watching on a major platform like Netflix, Prime Video or YouTube, KoalaSync is designed for smooth, browser-based watch parties.
+
+
+✨ CORE FEATURES
+No account required. No tracking. Just create a room, invite your friends, and start watching together.
+
+• Real-Time Video Sync: Play, pause, seek, and watch together with fast synchronized playback across everyone in your room.
+• No Account Needed: Create a room and share the invite link. No emails, no passwords, no sign-ups. Pick a nickname or let KoalaSync generate one for you.
+• Works Almost Everywhere: If the website uses a standard HTML5 video player, KoalaSync can usually sync it. Perfect for streaming sites, self-hosted media servers, and other websites.
+• Smart Binge-Watching: When a new episode loads, KoalaSync automatically pauses the lobby until everyone is ready. No spoilers, no one left behind.
+• Smart Audio Compressor: Tired of quiet dialogue and suddenly loud action scenes? Balance whispering, explosions, and music with a single click while you watch.
+• One-Click Invites: Send a smart invite link to your friends. When they open it, KoalaSync automatically configures the room so they can join instantly.
+• 15 Languages: Enjoy a native experience in English, German, French, Spanish, Brazilian and European Portuguese, Russian, Italian, Polish, Turkish, Dutch, Japanese, Korean, Simplified Chinese, and Ukrainian.
+
+
+
+🛡️ PRIVACY & SECURITY
+KoalaSync is built for private watch parties without unnecessary data collection.
+
+• No Tracking: Zero analytics, zero telemetry, and absolutely no behavior profiling.
+• Anonymous by Design: No accounts needed. Rooms can be joined with a simple nickname.
+• Ready Out of the Box: Install KoalaSync and start watching immediately using the official public relay server. No technical setup required.
+• RAM-Only Public Server: The official relay server operates entirely in volatile RAM. No databases, no stored watch history, no persistent room data. Room data exists only temporarily and disappears when the room closes.
+• Self-Hostable: Want full control? You can run your own private KoalaSync relay server via Docker in seconds. Self-hosting is optional and never required.
+
+
+
+🚀 HOW IT WORKS
+1. Install KoalaSync.
+2. Click "Create Room" to start a private watch party.
+3. Share the invite link with your friends.
+4. Open your favorite streaming site or media server.
+5. Select the active video tab.
+6. Press play. Everyone stays perfectly in sync.
+
+
+
+⚙️ UNDER THE HOOD
+KoalaSync is lightweight, transparent, and built with privacy in mind.
+
+• On-Demand Relay: Playback state is synchronized through a custom WebSocket-based relay server. There is no permanent background connection. The relay connection is maintained only while you're in a room and closes when you leave or automatically after two hours without a selected-video heartbeat.
+• No Media Streaming: KoalaSync does not stream, proxy, upload, download, or redistribute any video content. Everyone watches from their own browser on the original website.
+• Temporary Room State Only: The relay server only coordinates room state such as play, pause, seek position, active target, nickname, and readiness status.
+• Docker Self-Hosting: The relay server can be self-hosted with Docker if you prefer to run your own private instance.
+• Open Architecture: The project is designed to be inspectable, forkable, and easy to review.
+
+
+
+💻 OPEN SOURCE
+KoalaSync was built by a solo developer who needed a fast, secure way to watch movies with friends. The code is fully transparent under the MIT license: audit it, fork it, improve it, or self-host your own relay server.
+
+Found a bug or have a feature idea? Open an issue on GitHub. Contributions and code reviews are always welcome.
+
+• Website: https://sync.koalastuff.net
+• GitHub: https://github.com/Shik3i/KoalaSync

docker-compose.yml

@@ -1,4 +1,3 @@
-version: '3.8'
 
 services:
   server:

docs/AI_INIT.md

@@ -0,0 +1,161 @@
+# KoalaSync AI Onboarding (AI_INIT.md)
+
+Welcome to the KoalaSync project. This file is the primary entry point for any developer or AI agent working on this codebase. It defines the architecture, non-negotiables, and workflows required to maintain the stability and security of the system.
+
+> [!IMPORTANT]
+> **Privacy & Data Sovereignty**: KoalaSync follows a strict **Zero-External-Requests Policy**: The extension and website must not make requests to any third-party domains (Google Fonts, CDNs, etc.). All assets (fonts, icons, scripts) must be self-hosted or use system defaults.
+> - **Font Stack**: Use a modern system font stack (e.g., -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif) to maintain a premium look without external dependencies. Prohibit the use of `@import` or `<link>` for external font services.
+> 
+> [!IMPORTANT]
+> **Communication Standard**: Be concise, concrete, and professional. Match the user's language when practical, explain risky changes before making them, and report exactly what was changed and verified. Do not use joke protocols or intentionally broken language in contributor-facing work.
+
+---
+
+## 1. Project Overview
+KoalaSync is a specialized tool for **synchronized video playback** across multiple remote peers. It supports YouTube, Twitch, and native HTML5 video elements. 
+- **Users**: Friends or groups wanting to watch synchronized content together.
+- **Workflow**: A user creates a room, shares an invitation link, and all peers in that room are synchronized via a Node.js relay server.
+- **Identity**: Users are identified by a unique hex `peerId` combined with a customizable `username`.
+
+## 2. Repository Structure
+- `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).
+  - **`build.cjs`**: Static site compiler using the repository's build dependencies. Translates `template.html` + `locales/*.json` → `www/`, generates the sitemap, and minifies HTML/CSS/JS.
+  - **`www/` is auto-generated**: Never edit files in `www/` directly. Always edit source files (`template.html`, `style.css`, `styles/*.css`, `app.js`, `lang-init.js`, `locales/*.json`) and run `node website/build.cjs` to regenerate. `style.css` is the development manifest; `style.legacy.css` is an unloaded, byte-identical migration reference. Production creates page-specific and render-priority CSS bundles from `styles/*.css`; CSS/JS are output as `.min.*` files and stale generated assets are removed on each build.
+- `shared/`: **Single Source of Truth** for protocol constants, event names, blacklist data, and generated usernames.
+- `scripts/`: Development utilities (e.g., `build-extension.cjs`).
+- `docker-compose.yml`: Root-level orchestration for the relay server.
+
+> [!IMPORTANT]
+> **Single Source of Truth**: `shared/constants.js`, `shared/blacklist.js`, and `shared/names.js` are the master shared files. They must be synchronized to the `extension/shared/` directory using `node scripts/build-extension.cjs`.
+> - **Extension Modules** (`background.js`, `popup.js`) import directly from `./shared/constants.js`.
+> - **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. [../README.md](../README.md) – User, developer, and self-hosting overview.
+2. [README.md](README.md) – Documentation map by role.
+3. [ARCHITECTURE.md](ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol.
+4. [../extension/README.md](../extension/README.md) – Extension components, tab structure, and loading process.
+5. [SYNC_GUIDE.md](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. 
+- **Automated Injection**: The build script (`node scripts/build-extension.cjs`) automatically injects `EVENTS`, `HEARTBEAT_INTERVAL`, and episode utility functions into `content.js` using marker-based replacement (see `../scripts/README.md` for marker details).
+- **Maintenance**: After modifying any root `shared/` file, run the build script. No manual mirroring is required.
+
+## 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 |
+| `episode-utils.js` | Shared episode parsing, imported by background and injected into content |
+| `title-privacy.js` | Tab/media title privacy normalization and sanitization |
+| `page-api-seek-overrides.js` | Page-level seek bridge for site-specific player APIs |
+| `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`.
+- **Tab Structure**: Must maintain the visible **Room**, **Sync**, **Settings**, and **Status** tabs. The hidden **Dev** tab is available only for developer diagnostics.
+- **Appearance modes**: Preserve `system`, `light`, and `dark` behavior and the Eucalyptus, Cyber, and Graphite palettes.
+- **CSS variables**: Use the semantic tokens defined in `popup.html` (`--bg`, `--card`, `--accent`, `--text`, `--text-muted`, `--success`, `--warning`, and `--error`). Do not hard-code the retired indigo/slate palette or bypass palette-specific token overrides.
+
+## 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.
+- **Host Control Mode**: In `host-only` rooms, only the host and promoted controllers may initiate room-moving playback events. Both client-side UX and server-side gates must remain intact.
+- **Dual Heartbeat**: 
+    - **Background Heartbeat (1m)**: Ensures session persistence even without a video element.
+    - **Content Heartbeat (15s)**: Transmits current video metadata (time, title).
+- **Dead Peer Pruning**: Server "Reaper" disconnects peers after 5 minutes of total silence (no heartbeats or events).
+- **Deduplication**: Server kills old sockets if a user re-joins with the same `peerId` to prevent ghosts.
+- **Platform Specifics**: Specialized click-logic for YouTube (`.ytp-play-button`) and Twitch.
+- **pollSeekReady()**: Polling mechanism that checks `video.readyState` before acknowledging sync.
+- **SW Keep-alive**: Use of `chrome.alarms` to prevent the Manifest V3 Service Worker from suspending.
+- **Diagnostics**: The visible **Status** tab provides real-time access to connection state, ping, logs, history, and underlying `<video>` state for troubleshooting.
+- **Persistence**: `peerId` and `username` must be stored to remain stable across sessions.
+- **Title Privacy**: Do not accidentally reintroduce tab/media title sharing when users disabled or reduced it.
+- **Room ID Format**: Room IDs are restricted to `[a-zA-Z0-9-]` only (alphanumeric + hyphens). This is enforced server-side.
+
+## 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 natively.
+- **Server Transport**: Restricted to `websocket` only. Polling is disabled.
+- **Docker Context**: The Docker build must run from the **Repo Root**.
+- **Content Script Scope**: `bridge.js` is the only static content script in the manifest and runs on `https://sync.koalastuff.net/*` at `document_start`. Video control scripts are injected only into the selected tab via `chrome.scripting`; do not add broad persistent video content-script matches.
+- **Self-Hosting Salt**: Production/self-hosted relay examples must include a unique `SERVER_SALT` so room-password hashes are not derived with the public fallback salt.
+- **Strict Backward & Forward Compatibility (Store Delay Rule)**: Browser extensions are distributed through stores (e.g., Chrome Web Store, Firefox Add-ons) which can take up to 2 weeks to approve updates. Therefore, the server MUST NOT reject older extension clients unless a critical protocol version bump is explicitly authorized, and new extension versions MUST remain fully operational when connected to older servers (e.g., by silently falling back if a new feature is not supported). This is a core architectural requirement.
+
+## 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.
+
+## 10. Common Workflows
+
+## CRITICAL: Git & Release Rules
+
+- **NEVER** push, commit, tag, or release without explicit user instruction.
+- **NEVER** retag or force-push without explicit instruction.
+- **NEVER** create tags for documentation-only or README changes.
+- **NEVER** run `git push`, `git tag`, `git commit` unless the user says "push", "commit", or "tag".
+- Only the user decides when to commit, push, tag, or release.
+- Ask before any git write operation.
+
+### ⚠️ Pre-Session Git Sync (MANDATORY)
+Before starting any task, committing, or pushing, you **MUST** run `git pull --rebase` to ensure your local branch is up-to-date with `origin/main`. CI pipelines and other agents may push commits concurrently. Skipping this step will cause merge conflicts and rejected pushes.
+
+### Releasing a New Version (CRITICAL WORKFLOW FOR AI AGENTS)
+> [!CAUTION]
+> **AI AGENTS MUST FOLLOW THIS EXACT SEQUENCE WHEN RELEASING A NEW VERSION OR TAGGING.**
+> 
+> **🚫 NO MANUAL VERSION BUMPING**: You MUST **NEVER** manually modify the version strings in `package.json`, `extension/manifest.base.json`, or `website/version.json`. The GitHub Actions CI pipeline automatically extracts the version from the git tag (e.g. `v2.0.5` -> `2.0.5`), injects it into all target files, and commits the updates back to `main` with `[skip ci]`. Manual bumps will cause merge conflicts and build failures.
+> - **Website Versioning**: **NEVER** manually modify generated version strings in `website/www/`. The website build injects version data from `website/version.json` into generated output.
+1. **MANDATORY SYNTAX & LINT CHECKS**: Before staging, committing, or pushing any changes, you **MUST** run both checks on every modified JavaScript file:
+   - **Syntax Validation**: Run `node -c` on every single modified JavaScript file (e.g., `node -c extension/background.js` and `node -c extension/content.js`). **NEVER** commit or push code that fails this check.
+   - **ESLint Validation**: Run `npm run lint` (or `npx eslint .`). The output must show **zero errors and zero warnings**. ESLint is configured to catch undefined variables, unused vars, unreachable code, and other semantic issues. **NEVER** commit or push code that fails this check.
+2. Commit all verified code changes and push to `main`.
+3. 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.
+   - **🚫 TAG IMMUTABILITY**: Once a tag is pushed to `origin`, it is **PERMANENT**. You MUST **NEVER** reuse, move, or force-push an existing tag — not even to "fix" a mistake. If a release is missing a fix, increment the version and create a **new** tag (e.g., `v1.7.0` → `v1.7.1`). Tags are immutable identifiers; moving them breaks CI pipelines, corrupts the release history, and causes unreproducible builds.
+   - **🚫 WHEN NOT TO TAG**: Do NOT create a release tag for changes that do NOT affect the shipped extension or server artifacts. Website text changes, documentation updates (`.md` files), and landing page content do NOT require a version tag. Tags trigger the full CI pipeline (Docker build, extension packaging, GitHub Release) — running this for a typo fix wastes CI resources and creates meaningless releases. Only tag when extension code (`extension/`), server code (`server/`), or shared protocol constants (`shared/`) have changed.
+4. 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.
+5. Verify the release builds on GitHub Actions.
+
+### 🚫 Force Push Policy
+> [!CAUTION]
+> **Force pushing (`git push --force` or `git push -f`) is FORBIDDEN without explicit user confirmation.**
+> - If a push is rejected due to a non-fast-forward conflict, you **MUST** run `git pull --rebase` first.
+> - If a force push is absolutely required (e.g., squashed history, amended commits), you **MUST** ask the user for explicit permission with a clear explanation of why it's necessary. Never force-push autonomously.
+> - This applies to both branches (`main`) and **tags** (see Tag Immutability above). Force-pushing tags is doubly destructive. Never do it.
+
+### Adding a Protocol Event
+1. Add the event name to `shared/constants.js`.
+2. Run the build script (`node scripts/build-extension.cjs`).
+3. Implement the handler in `server/index.js` and `background.js`.
+
+### Making Website Changes
+1. Edit source files in `website/` (`template.html`, `style.css`, `styles/*.css`, `app.js`, `lang-init.js`, or `locales/*.json`).
+2. Run the compiler: `node website/build.cjs`. This generates the multilingual pages in `www/` and minifies CSS/JS.
+3. Verify the sources and generated contract: `node --check website/app.js`, `node --check website/lang-init.js`, `node scripts/test-website-locales.mjs`, and `node scripts/test-website-theme.mjs`.
+4. Test locally: `npx serve website/www` or `python3 -m http.server 8080 -d website/www`.
+5. Commit the source changes only. `website/www/` is generated and gitignored.
+
+### Testing Locally
+1. Run the build script: `node scripts/build-extension.cjs`.
+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 **Status tab** to verify real-time connection state, logs, and video element metadata.
+
+### Locking Old Versions
+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.

docs/ARCHITECTURE.md

@@ -0,0 +1,75 @@
+# KoalaSync Architecture
+
+This document describes the communication flows and internal logic of the KoalaSync system.
+
+## 1. Extension Connection (Lazy Connect)
+- **Initialization**: On startup, `background.js` reads settings (Server URL, Username, Last Room) from `chrome.storage.sync`. No WebSocket connection is established at this point.
+- **On-Demand Connection**: The extension only connects when needed — either the user opens the popup with saved room credentials, or when actively in a room. When not in a room, no connection exists. This improves privacy (IP not exposed while idle) and reduces battery/network usage.
+- **WebSocket Handshake (when connecting)**:
+  1. Background creates a `new WebSocket` to `/socket.io/?EIO=4&transport=websocket&version=1.0.0`.
+  2. Server performs security checks:
+     - **IP Rate Limit**: Checks if the IP has exceeded connection limits.
+     - **Protocol Version**: Client must match the server's protocol (currently `1.0.0`).
+  3. Server responds with Engine.IO handshake (`0`) and the client joins the namespace (`40`).
+- **Room Join**: Background emits `JOIN_ROOM` containing `roomId`, `password`, `peerId`, and `username`.
+- **Deduplication**: If a user joins with a `peerId` that already has an active socket, the server kills the old socket to prevent "Ghost Peers". Deduplication re-validates after acquiring the room creation lock to avoid kicking the wrong socket during concurrent joins.
+
+## 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, including videos inside Shadow DOM (YouTube, Netflix, etc.).
+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. Timeout IDs are cleaned up immediately to prevent memory leaks.
+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 via `SERVER_COMMAND` (which includes the original `senderId` for correct ACK routing) and call `video.play()`, `video.pause()`, or `video.currentTime = targetTime`.
+6. **ACK Routing**: `content.js` echoes the `commandSenderId` back in `CMD_ACK`, ensuring the `EVENT_ACK` is routed to the correct initiating peer even when multiple commands arrive concurrently.
+
+## 3. Two-Phase Force Sync
+Ensures all peers are buffered and synchronized 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`. (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. 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.
+- **Reconnect Strategy (while in room)**: Aggressive backoff — 500ms base, 1.5x multiplier, capped at 5s. Max 20 attempts before marking as failed. Events are queued during disconnect and flushed after namespace rejoin. When not in a room, no reconnection occurs.
+
+> [!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` (30s interval) to prevent the Manifest V3 service worker from suspending while in an active room. On wake, runtime state is restored from `chrome.storage.session` via `ensureState()`.
+- **Reconnect Visualization**: Badge shows "..." (orange) during reconnect. Popup displays "Reconnecting..." with attempt counter.
+- **Rate Limiting**: Server-side per-socket and per-IP rate limits to prevent sync-spamming or simple DoS. Public health endpoints are limited to 10 requests/minute/IP and cached server-side for 60 seconds, wrong admin-metrics bearer attempts to 5 requests/minute/IP, and room discovery to one request every 10 seconds per socket. Real client IP is taken from the trusted reverse proxy hop, so the Node port must stay private behind Caddy or another trusted proxy.
+- **Room Creation Lock**: Per-room mutex prevents race conditions when multiple peers join a new room simultaneously.
+- **CORS**: Allows `chrome-extension://` origins for WebSocket fallback compatibility.
+- **Message Buffer**: `maxHttpBufferSize` set to 4KB to accommodate large `JOIN_ROOM` payloads.
+- **Process Guards**: `uncaughtException` and `unhandledRejection` handlers prevent silent server crashes.
+- **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.
+
+## 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 synchronized copy of `EVENTS` and constants.
+- **Automation**: The `npm run build:extension` script automatically injects `EVENTS`, `HEARTBEAT_INTERVAL`, and `episode-utils.js` functions 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.

docs/CHANGELOG.md

@@ -0,0 +1,428 @@
+# KoalaSync Changelog
+
+All notable changes to the KoalaSync browser extension and relay server.
+
+---
+
+## [v2.6.3] — 2026-07-15
+
+### Fixed
+- **Extension: Host-access recovery races** — Prevents stale permission grants, reinjection retries, closed tabs, and rapid target changes from reactivating or clearing the wrong video tab.
+- **Extension: Cross-browser host patterns** — Uses Firefox-compatible match patterns for local servers while preserving exact Chromium port scopes.
+- **Extension: Force-sync target integrity** — Keeps sampled playback time and acknowledgements bound to the selected tab during recovery and target changes.
+
+## [v2.6.2] — 2026-07-15
+
+### Added
+- **Website: Site-access recovery guide** — Added an English help page and a localized banner across every landing-page language.
+
+### Fixed
+- **Extension: Withheld website access recovery** — Detects browser-withheld host access, shows a localized allow-access action, requests only the selected website origin, and resumes the selected tab after access is granted.
+- **Extension: Target-tab reliability** — Hardened permission recovery against rapid tab changes, navigation, closed tabs, service-worker restoration, and stale pending state.
+- **Browser compatibility** — Uses Chrome's toolbar access request only when available, with a direct user-gesture permission fallback for Firefox and older Chromium browsers.
+
+---
+
+## [v2.6.1] — 2026-07-15
+
+### Fixed
+- **Extension: Episode Lobby peer list** — Peer names in the lobby are now rendered as text instead of markup. A peer could previously put HTML in their username and have it rendered in everyone else's popup, which allowed loading remote images (leaking viewer IP addresses) and spoofing the readiness badges. Scripts were already blocked by the extension's content security policy.
+
+### Changed
+- **Release checks: AMO validation** — `npm run verify` now runs Mozilla's `addons-linter` against the built Firefox artifact with `--warnings-as-errors`, and ESLint enforces `no-unsanitized`, so upload-blocking issues surface locally instead of at submission time.
+
+---
+
+## [v2.6.0] — 2026-07-15
+
+### Added
+- **Extension: Appearance controls** — Added localized system, light, and dark theme options with an early theme initializer to avoid flashes during popup startup.
+
+### Changed
+- **Extension: Popup and settings redesign** — Unified controls, status surfaces, colors, icons, badges, and accessibility behavior; settings are now organized into mutually exclusive accordion groups.
+
+### Fixed
+- **Extension: Episode Lobby reliability** — Prevented the lobby from remaining stuck in a loading state and stopped episode transitions from triggering on non-episodic media.
+- **Extension: Tab-title normalization** — Notification counters such as `(14)`, `[7]`, and `(99+)` are removed reliably without stripping legitimate large numeric titles.
+
+---
+
+## [v2.5.4] — 2026-07-08
+
+### Changed
+- **Extension: Refined clutter blacklist** — Removed `localhost` and cloud storage providers (`drive.google.com`, `dropbox.com`, `onedrive.live.com`, `icloud.com`) from the domains blacklist so that local web development servers and tabs hosting video files in cloud storage are no longer hidden under "Hide Clutter Tabs".
+
+---
+
+## [v2.5.3] — 2026-07-02
+
+### Fixed
+- **Extension: Disney+ force sync and seeking** — Fixed force sync on Disney+ failing or jumping to wrong positions. The extension now relies solely on accurate player-API time and fails cleanly when it isn't available yet, instead of falling back to unreliable raw video data.
+- **Extension: Force-sync accuracy** — When syncing to the group, peers whose current position isn't known yet (e.g. a Disney+ peer that just loaded) no longer pull the sync target toward the start of the video.
+- **Extension: Disney+ Host Control Mode** — Regular Disney+ content is no longer misclassified as a live stream, which had silently disabled the desync dialog and snap-back for guests in host-controlled rooms. YouTube and Twitch live detection is unchanged.
+- **Extension: Disney+ episode auto-sync** — Episode transitions and the "waiting for peers" lobby flow now work reliably on Disney+ again.
+
+---
+
+## [v2.5.2] — 2026-07-02
+
+### Added
+- **Extension: Privacy title controls** - Advanced users can now disable sending browser tab titles separately from media titles. Media titles can still be sent in full, reduced to detected episode identifiers such as `S01E04`, or hidden entirely. Defaults remain full titles for backwards compatibility.
+- **Relay: Cleaner restart handling** — Connected clients are now disconnected explicitly during relay shutdown so reconnects recover more predictably.
+- **Relay: Stronger abuse protection** — Rapid room-leave spam is now rate-limited.
+- **Extension: Hidden remote seek diagnostics** — KoalaDev can use the hidden Dev tab to simulate remote seeks and inspect precise native/page-API timing while debugging playback integrations.
+
+### Changed
+- **Extension: Shared page-API seek bridge** — Netflix and Disney+ now use a common page-level seek bridge so private player APIs can be invoked from the page context while the default HTML5 path stays unchanged.
+- **Build: Release build timestamp** — Extension builds now inject a build timestamp into the hidden Dev tab for easier local package verification.
+
+### Fixed
+- **Extension: Disney+ precise sync** — Disney+ now reads time and seeks through the real page media-player API, and the temporary DOM timeline/button scraping fallback has been removed.
+- **Extension: Netflix seek reliability** — Netflix seeking keeps using the page player API with a safer session lookup path.
+- **Extension: Tab-title counter cleanup** — Leading browser notification counters such as `(14)` or `[7]` are removed from shared tab titles and matching logic without changing the existing privacy controls.
+- **Extension: Tab navigation reinjection** — Reinjecting the content script after selected-tab navigation now uses the same page-API-aware injection path.
+
+---
+
+## [v2.5.0] — 2026-06-29
+
+### Added
+- **Extension + Relay: Host Control Mode** — Room owners can now switch a room between open playback control and host-controlled playback. In host-only mode, guests stay synchronized but their local play, pause, and seek actions are not rebroadcast to the room.
+- **Backward-compatible Host Control rollout** — The extension only shows Host Control when the connected relay supports it, so users on older self-hosted servers do not see controls that cannot work yet.
+- **Extension: Clear host and guest states** — The popup shows the current control mode, host status, peer roles, and localized guest guidance so participants understand when playback is controlled by the host.
+- **Website: FAQ clarification for streaming access** — The landing page and FAQ structured data now state clearly that KoalaSync does not stream, host, share, or bypass access to video content. Every participant watches locally and needs their own access to services such as Netflix.
+
+### Changed
+- **Playback sync now follows the room's control setting** — When Host Control is enabled, only the host can drive room-wide playback changes; guests can still watch in sync without accidentally changing playback for everyone.
+
+---
+
+## [v2.4.6] — 2026-06-23
+
+### Fixed
+- **Room and settings are no longer stored in `chrome.storage.sync`** — Room ID, password, and username were being resurrected from synced storage on a fresh install (sync survives an uninstall in the user's Google account), which made the extension silently auto-connect to a dead room and appear permanently connected. `getSettings()` and all settings reads are now local-only, and legacy keys are actively purged from sync on install/update/startup. Only `onboardingComplete` and `dismissedHints` remain in sync.
+- **No server traffic while alone in a room** — When you are the only peer, heartbeats, force-sync, and episode auto-sync are now fully suppressed (previously the keepAlive heartbeat, force-sync, and episode lobby were still broadcast to an empty room). The solo state is re-evaluated live on every event — never cached — so the instant another peer joins, syncing resumes immediately, including an instant state push so the newcomer sees your current position without waiting for the next heartbeat.
+
+## [v2.4.4] — 2026-06-23
+
+### Changed
+- **Server: Event rate limit raised 30 → 50 per 10s**, and all connection/event/health rate-limit thresholds and windows extracted into named constants.
+- **Extension: Reconnect backoff tuned and jittered** — capped at ~8 attempts/60s (under the per-IP connection limit) with ±20% jitter to de-synchronize reconnect herds after a server blip.
+- **CI: Added a verification workflow** running lint, tests, audits, and builds on every push/PR; the release build now uses `npm ci`.
+
+### Fixed
+- **Extension: Offline event-queue flush is now paced** (small batches instead of one synchronous burst) so a reconnect after a long outage no longer trips the server event limit and gets disconnected on rejoin.
+- **Extension: Ping liveness tolerates one missed PONG** — a reconnect is forced only after 2 consecutive misses (~20s) instead of a single 5s timeout, avoiding spurious drops under transient load.
+- **Extension: `socket.send()` failures are caught and re-queued** instead of losing the event on a disconnect race.
+
+## [v2.4.3] — 2026-06-19
+
+### Added
+- **Two new languages: Ukrainian (`uk`) and Chinese (`zh`, Simplified)** — added across the extension (UI strings + Chrome `_locales`) and the website (localized pages, hreflang/Open Graph/schema tags, language selector), bringing the total to 15 languages.
+
+### Changed
+- **Play/pause sync coalescing** — The content script now collapses rapid bursts of native play/pause events (source swaps, ABR/quality switches, ad transitions, page teardown) into a single relayed command: the first event is sent instantly and a short 150ms window absorbs the rest. This cuts redundant relay traffic and stops bursts from tripping the server's per-socket event rate limit.
+
+### Fixed
+- **zh/uk translation quality** — Corrected systematic machine-translation word-sense errors in the two new locales (e.g. "Play", "Status", "Leave Room", "Clear", "Open", "peers", and audio compressor terms) and translated the remaining English leftovers.
+- **Relay logging** — An `EVENT_ACK` aimed at a peer that already left is now logged quietly instead of as a `[SECURITY]` cross-room event, so genuine cross-room attempts stand out in the logs.
+
+## [v2.4.2] — 2026-06-19
+
+### Changed
+- **Extension: Optimized uninstall URL registration** — Extracted registration into a reusable, race-condition-protected `initUninstallURL()` helper. It registers the uninstall feedback URL with browser context on both extension installation/update and browser startup to prevent state loss, without storing or sending an installation token.
+
+## [v2.4.1] — 2026-06-19
+
+### Added
+- **Extension: Onboarding tour now has a closing step** — The first-run tour ends on a dedicated "You're all set!" card (the `ONBOARDING_5` copy that already existed in all 13 locales but was never shown). The tour no longer stops abruptly on the username step.
+- **Extension: One-click invite from the empty peer list** — The "No peers yet" state now shows a **📋 Invite Link** button that copies the invite link to the clipboard, so users can share it without hunting for the field.
+
+### Changed
+- **Extension: Cleaner onboarding welcome** — Step 1 is now a centered welcome card instead of spotlighting the logo title. Added a guard so target-less tour steps center cleanly.
+- **Website: Mobile comparison table** — The KoalaSync vs Teleparty table stacks into per-feature cards on phones instead of forcing horizontal scrolling; feature descriptions are shown again on mobile.
+
+### Fixed
+- **Extension: Onboarding step counter/progress placeholders** — Static `Step 1 of 3` / 33% fallbacks in `popup.html` corrected to match the actual 5-step tour (`Step 1 of 5` / 20%).
+- **Website: Mobile navigation restored** — The header hamburger menu was hidden by a `display:none !important` rule, leaving the nav links unreachable on phones. Re-enabled, with spacing kept comfortable down to ~320px.
+- **Website: Hero alignment on mobile** — A fixed-width extension mockup forced the hero grid column wider than the container, shifting all hero content off-center (larger left margin than right). The mockup is now responsive (`width:100%/max-width` + `minmax(0,1fr)` grid track).
+- **Website: Reveal-animation fallback** — Added a `<noscript>` style fallback and `IntersectionObserver` feature guards so scroll-revealed content can never stay invisible if JavaScript is disabled or unsupported.
+
+## [v2.4.0] — 2026-06-16
+
+### Added
+- **Extension: Lazy WebSocket connection** — The extension no longer maintains a permanent WebSocket connection to the relay server. Instead, the connection is established only when actively in a room or when the popup is opened with a saved room configuration. This improves privacy (IP is not exposed while idle), reduces battery/network usage, and prevents the server from tracking online status of inactive users. Automatic reconnect is guaranteed while in a room — zero behavior change during active sync sessions. See `connectIntent` flag in `background.js`.
+- **Extension: Episode title regex unification** — `extractEpisodeId()` had inconsistent regex patterns between `background.js` and `content.js`. The content script correctly matched Crunchyroll-style separators (`S01/E01`) while the service worker's stricter pattern (`[\s\-\.]*`) silently rejected them, causing episode lobby sync failures. Now unified to `[^a-zA-Z0-9]*` via shared `episode-utils.js`.
+- **Unit tests: `rate-limiter` and `episode-utils`** — 12 test groups for rate-limit functions and 30+ assertions for episode title parsing, covering all 6 separator types (dash, dot, slash, colon, comma, space). Run automatically via `npm run verify`.
+
+### Changed
+- **Server: Rate limiter extracted to `rate-limiter.js`** — 6 rate-limit functions, all rate-limit Maps, and cleanup intervals moved from `index.js` (149 lines). `index.js` now imports via facade pattern with re-exports for backward compatibility.
+- **Extension: Episode utilities extracted to `episode-utils.js`** — `extractEpisodeId()` and `sameEpisode()` deduplicated from `background.js` and `content.js`. The shared module is imported as an ES module by the service worker and injected into the content script IIFE by the build script.
+- **Build: `"type": "module"` in root `package.json`** — All scripts standardized to ESM (`.mjs`) or explicitly CommonJS (`.cjs`). Eliminated Node.js `MODULE_TYPELESS_PACKAGE_JSON` warnings.
+- **Build: 4 CJS scripts renamed to `.cjs`** — `build-extension.js`, `test-content-video-finder.js`, `test-locales.js`, `website/build.js`.
+
+### Fixed
+- **Server: npm audit resolved** — `ws` package vulnerability (CVE-2024-37890) fixed. Zero vulnerabilities in production dependencies.
+- **Pop-up: Connection status flicker fixed** — Removed hardcoded `disconnected` state on every pop-up open. Status now reflects actual background state from the first frame.
+- **Pop-up: Join button timeout improved** — No longer blindly re-enables after 15s. Polls connection status and extends window if still connecting.
+- **Pop-up: Validation failure state cleanup** — Custom server URL validation errors now properly reset `isProcessingConnection` and `joinBtnTimeout`.
+- **Extension: `WEB_JOIN_REQUEST` channel leak fixed** — Missing `sendResponse()` call when already in the target room.
+- **Extension: `LEAVE_ROOM` now clears `roomId` from storage** — Prevents phantom auto-reconnect on browser restart after explicit leave.
+- **Extension: Reconnect attempt counters reset on leave** — Prevents stale `reconnecting` status display after intentional disconnect.
+
+## [v2.3.2] — 2026-06-16
+
+### Changed
+- **Extension: Refined Spanish, Italian, and Portuguese translations**: Complete manual review and improvement of all Spanish (`es`), Italian (`it`), Portuguese — Brazil (`pt-BR`), and Portuguese — Portugal (`pt`) locale files for both the extension UI and the landing website. Thanks to [@Kaia-Alenia](https://github.com/Kaia-Alenia) for the native-quality translations.
+
+### Fixed
+- **Extension: Locale typos and corrupted characters fixed**: Repaired a Korean refresh button label (`Refreschi` → `새로고침`), a corrupted Korean connection status string (`연kel` → `연결`), a Korean character contaminating a Japanese string (`의` → `の`), and a Dutch typo (`cmmuniceren` → `communiceren`).
+- **Server: Admin token length leak fixed (timing side-channel)**: `isAdminMetricsAuthorized()` returned early when the provided buffer had a different length than the expected token, leaking the token length via response timing. Now `crypto.timingSafeEqual` runs in constant time on every attempt regardless of length match. Reported by [@Kaia-Alenia](https://github.com/Kaia-Alenia).
+
+---
+
+## [v2.3.1] — 2026-06-15
+
+### Fixed
+- **Server: Concurrent peer join race condition and teardown error handling**
+
+### Changed
+- **Server: Smart unhandled rejection handling (exits after 5/min instead of 1)**
+- **Server: Optimized admin health metrics allocation**
+
+---
+
+## [v2.3.0] — 2026-06-14
+
+### Added
+- **Extension: New Interactive Onboarding Tour**: A fully redesigned, interactive step-by-step onboarding experience.
+- **Extension: Auto-Switch to Sync Tab**: The UI now intelligently switches to the Sync tab when you join a room to guide video selection.
+- **Extension: Uninstall URL Integration**: Prepared an uninstall URL setup that works natively across Chrome and Firefox, cleanly attaching browser context for analytics.
+
+### Fixed
+- **Extension: Infinite Seek Loop Prevention**: Replaced the fragile time-based seek suppression with an exact target-time verification mechanism, entirely eliminating infinite seek loops on slow buffers.
+- **Extension: Zombie Connections Resolved**: Implemented a forced disconnect upon ping timeouts, ensuring the extension reliably auto-reconnects when the WebSocket hangs in a half-open state.
+- **Extension: Room Switching Architecture**: Joining a new room while already connected now explicitly severs the old connection first, preventing state cross-contamination. 
+- **Extension: Join/Leave Race Conditions**: Added UI locks to prevent users from accidentally sending conflicting connection commands via rapid double-clicking.
+- **Extension: Same-Room Invite Bypass**: Clicking an invite link for the room you are currently in no longer triggers a redundant reconnect, instead instantly confirming the join.
+- **Extension: Audio settings now propagate immediately to video tabs**: Changes made in the audio options page are now instantly applied to the active video tab. Previously, settings saved to `chrome.storage.local` were not picked up by the background listener, which only watched `chrome.storage.sync`.
+- **Extension: Audio compressor now logs enable/disable state and resume failures**: The compressor reports when it is activated or bypassed, and warns if the `AudioContext` cannot be resumed (e.g. browser autoplay policy requires a user gesture on the page first).
+- **Extension: Video heartbeat no longer sent when alone in a room**: The full media metadata `PEER_STATUS` is now only emitted when other peers are present. The session keepalive (background heartbeat) continues to run unaffected, preventing the server reaper from disconnecting idle peers.
+- **Server: Increased `failedAuthAttempts` eviction threshold from 50k to 200k**: Reduces frequency of expensive batch evictions under high auth-failure volumes, smoothing heap usage.
+
+---
+
+## [v2.2.4] — 2026-06-10
+
+### Fixed
+- **Extension: Error notifications now respect `browserNotifications` setting**: Server error events (e.g. "Server is restarting") no longer trigger a browser notification when the user has disabled notifications in the extension settings.
+- **Server: Misleading reconnect message corrected**: The graceful shutdown message no longer tells users to manually reconnect — the extension handles this automatically.
+
+---
+
+## [v2.2.3] — 2026-06-10
+
+### Added
+- **Artifact Attestations (Supply Chain Security)**: All release artifacts (Docker images, extension ZIPs) are now published with signed [SLSA provenance attestations](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations) via `actions/attest@v4`. Anyone can verify that an artifact was built from this repository using `gh attestation verify`.
+- **Admin health: `rateLimits.denied` counters**: New rolling counters track actual rate-limit denials (429 responses), separate from `rateLimits.trackedClients` which reports unique IPs in the tracking window.
+- **Docker HEALTHCHECK**: Container health is now checked every 30s via `GET /health`.
+- **`npm start` script**: Server can now be started with `npm start`.
+
+### Fixed
+- **Server: `activeLobby` no longer silently overwritten**: If a second peer sends `EPISODE_LOBBY` while a lobby is already active, the request is now ignored instead of destroying the first peer's lobby.
+- **CORS log sanitization**: Rejected origin headers are sanitized (`\r\n` stripped) to prevent log injection.
+- **Extension: pagehide resource leak**: `keepAlivePort`, `lobbyPollTimer`, heartbeats, and `MutationObserver` are now properly cleaned up when a tab is hidden or enters bfcache.
+- **Extension: unhandled storage rejections**: `chrome.storage.session.set()` calls in the disconnect handler now have `.catch(() => {})`.
+- **`'Pixel'` duplicate in name generator**: Second occurrence replaced with `'Nitro'` for better name diversity.
+- **`'opposum'` typo**: Corrected to `'opossum'` in the emoji map and added `'Opossum'` to `USERNAME_NOUNS`.
+- **Test reliability**: `test-server-routes.mjs` now sets `ADMIN_METRICS_TOKEN` before importing the server module, fixing standalone test execution.
+- **`MAX_PEERS_PER_ROOM` konsistent**: `.env` auf 25 gesetzt (wie `.env.example`).
+- **pt-BR.json duplicate removed**: Duplicate `FOOTER_DISCLAIMER` key removed from website locale.
+
+### Changed
+- **Admin health: `rateLimitEntries` renamed to `rateLimits.trackedClients`**: The field now accurately describes that it tracks unique clients in the rate-limit window, not denial counts. Update your json_exporter/Grafana config accordingly.
+- **README restructured**: Sections reordered by progressive technical depth. New "Supply Chain Security" subsection under "For Developers & Self-Hosters" with verification commands.
+
+---
+
+## [v2.2.2] — 2026-06-09
+
+### Added
+- **Chrome Web Store i18n Support**: Added `default_locale: "en"` to manifest and created `_locales/*/messages.json` for all 13 supported languages. This unlocks the language selection dropdown in the Chrome Web Store dashboard, allowing translated store listings (title, description) per locale. The extension's own UI translations (`locales/*.json` + `i18n.js`) remain unchanged.
+- **Locale test coverage**: Extended `scripts/test-locales.js` to validate all `_locales/*/messages.json` files (correct format, required keys, no duplicates) and verify `default_locale` is set in the manifest.
+
+### Fixed
+- **Copy Logs button alignment**: Removed stray `margin-top: 8px` inherited from `.secondary` class that pushed the button 8px down in the connection status row.
+
+---
+
+## [v2.2.1] — 2026-06-09
+
+### Added
+- **Server Ping Display**: Measures round-trip latency to the relay server via application-level ping/pong events. The extension sends `PING { t }` every 15 seconds; the server responds with `PONG { t }`. Round-trip time is calculated client-side and displayed in the Status tab, color-coded (<50ms green, 50–150ms yellow, >150ms red). No ping value is shown when disconnected or if the server does not respond within 5 seconds.
+- **Peer Ping Response (Future-Proof)**: The extension can now respond to incoming `PING { t, sender }` events from other peers by sending back `PONG { t, target: sender }`. The relay server forwards `PING` to the target peer and routes `PONG` back to the original sender. Both client and server validate that peers are in the same room before forwarding/routing. Peer-to-peer ping initiation will be activated in a future extension update without requiring a server restart.
+
+---
+
+## [v2.2.0] — 2026-06-08
+
+### Added
+- **Web Audio API Compressor**: Built-in audio dynamic range compression with four presets (Recommended, Dynamic Range, Vocal Enhancement, Smooth) and fully customizable sliders (threshold, ratio, knee, attack, release). Uses dry/wet crossfade (40ms linear ramp) to avoid clicks. Configured via the new Audio Options page accessible from the Settings tab.
+- **Audio Options Page** (`audio-options.html`): Dedicated settings page with master toggle, compressor preset selector, real-time custom sliders, and equalizer placeholder. Dark theme matching the popup design.
+- **Feature Hint System**: Generic `dismissedHints` array in sync storage for announcing new features. First hint highlights the Audio Options entry in Settings. Extensible for future features.
+
+### Changed
+- **Support Links**: Static footer badges on the Settings and Status tabs linking to the developer's support page. README and website footer updated with a Support KoalaSync badge.
+
+### Fixed
+- **Portuguese (PT) locale**: Removed Italian contamination — "sincronizzazione" → "sincronização", "tempo reale" → "tempo real", "Link di Invito" → "Link de Convite", "Sair della Sala" → "Sair da Sala".
+- **Korean locale**: Fixed broken character in `HOWTO_STEP_2_TEXT` (`클rip보드` → `클립보드`).
+- **Website COMP_FEAT_6_KOALA**: Normalized from inconsistent "6 Languages" to "13 Languages" across all locale files (en, de, es, fr, pt-BR, ru).
+- **Debug report showing wrong logs**: Fixed `logs.slice(-50)` and `history.slice(-20)` in the "Copy Debug Report" feature. Since `addLog()` and `addToHistory()` use `unshift` (inserting entries at index 0), the arrays are ordered newest-first. `slice(-N)` took the N **oldest** entries instead of the N **newest**. Changed to `slice(0, N).reverse()` to correctly include the most recent logs and display them chronologically.
+
+---
+
+## [v2.1.2] — 2026-06-06
+
+### Fixed
+- **Episode guard regex**: Fixed `isDifferentEpisode()` not detecting episode changes when the MediaSession title uses `Sxx:Exx` format (colon separator, as used by Jellyfin/Emby). The regex character class `[\s\-\.]` was replaced with `[^a-zA-Z0-9]` to match **any** non-alphanumeric separator between season and episode numbers, preventing play/pause/seek commands from a different episode leaking through and incorrectly manipulating a peer's playback.
+- **Per-device storage isolation**: Migrated `username`, `roomId`, `password`, `serverUrl`, and `useCustomServer` from `chrome.storage.sync` (synced across Google account) to `chrome.storage.local` (per-device). This prevents the extension from automatically joining the same room with the same name on multiple devices. Existing user data is migrated silently on first run; all preferences (`filterNoise`, `autoSyncNextEpisode`, etc.) remain synced.
+
+### Changed
+- Added one-time migration fallback in `getSettings()` and popup `init()` to copy existing user settings from `storage.sync` to `storage.local` on first launch after the update.
+
+---
+
+## [v2.1.0] — 2026-06-04
+
+### Added
+- Added full translation support for 7 new languages to both the browser extension popup settings and landing website: Italian (`it`), Polish (`pl`), Turkish (`tr`), Dutch (`nl`), Japanese (`ja`), Korean (`ko`), and European Portuguese (`pt`).
+- Implemented robust, centralized browser system language detection mapping `pt-BR` to Brazilian Portuguese and other `pt` locales (like `pt-PT`) automatically to European Portuguese.
+- Added flag emojis to language selector dropdowns in both the extension popup and landing/utility web pages for quicker visual identification.
+- Added 181 translation keys parity validation suite checks for the new languages.
+
+### Fixed & Hardened (Extension Audit)
+- Guarded all website `localStorage` interactions to prevent initialization/join flow script failures on privacy-hardened or cookie-blocked browser configurations.
+- Added robust validation null-guards to `chrome.runtime.onMessage` listeners across all extension scripts (`bridge.js`, `content.js`, `background.js`, `popup.js`) to reject unexpected runtime messages.
+- Guarded CustomEvent payload destructuring in `bridge.js` to ensure stability when receiving third-party page events.
+- Wrapped `video.currentTime` seeking adjustments during forced sync in content scripts with exception handling to absorb uninitialized video state DOMExceptions.
+- Added payload validation guards on incoming Socket.IO events within the background script's event handlers to secure against malformed server updates.
+- Prevented noisy browser console exceptions from context invalidation in target tabs by catching promise rejections on extension message dispatches.
+
+### Performance
+- Implemented in-memory language dictionary caching in the background script to completely avoid redundant extension package filesystem reads during translations.
+
+
+---
+
+## [v2.0.8] — 2026-06-03
+
+### Fixed
+- Fixed a bug where switching language inside the extension popup overwrote dynamic fields (such as active room ID, connection status, active server details, and video debug info) with default localized placeholder texts.
+- Fixed a version reporting mismatch where the copied logs (debug reports) and connection handshake parameters incorrectly reported the hardcoded `1.9.0` version instead of the actual installed manifest version.
+
+---
+
+## [v2.0.7] — 2026-06-03
+
+### Added
+- Added a `DEBUG_LOGGING` environment variable to the relay server (defaulting to `"0"` / disabled) to prevent console spam from verbose connection (`CONN`), room activity (`ROOM`, `DEDUPE`), and `CORS` events under load. Critical logs like `SERVER`, `SECURITY`, `AUTH`, and `ERROR` remain enabled at all times.
+
+---
+
+## [v2.0.6] — 2026-06-03
+
+### Performance & Security Hardening
+- Optimized failed authentication attempts cache eviction algorithm to $O(1)$ by exploiting Javascript `Map` insertion-order properties. This completely removes the previous array copying and sorting bottleneck, neutralizing a potential main-thread blocking DoS vector under heavy brute-force password traffic.
+
+---
+
+## [v2.0.5] — 2026-06-03
+
+### Security & Hardening
+- Hardened extension room idle auto-leave detection to correctly recognize when the target tab's video heartbeat goes stale (e.g., after tab navigation or media closure).
+- Exported cleaner graceful shutdown and lifecycle methods (`stopServerForTests`) from the relay server to prevent socket leaks and port-binding conflicts during verify checks.
+
+### Added
+- Added a validation step in `test-locales.js` to ensure the supported language list in `extension/i18n.js` is perfectly synchronized with the actual JSON translation files in the locales directory.
+- Added a robust route verification test suite (`scripts/test-server-routes.mjs`) covering rate limit throttling, caching headers, and admin metrics access control.
+
+---
+
+## [v2.0.4] — 2026-06-03
+
+### Security & Hardening
+- Hardened relay health endpoints against simple flood traffic: `GET /` and `GET /health` are now limited to 10 requests per minute per client IP.
+- Added lazy 60-second server-side caching for `GET /`, basic `/health`, and admin `/health` JSON responses to reduce repeated health-check work under noisy polling.
+- Added stricter brute-force throttling for invalid admin metrics bearer attempts.
+- Added startup warning for short `ADMIN_METRICS_TOKEN` values and documented that production Node ports must stay private behind Caddy or another trusted reverse proxy.
+- Lowered the default maximum peers per room to 25.
+
+### Added
+- Optional privacy-preserving admin metrics on `/health` when `ADMIN_METRICS_TOKEN` is configured and a valid bearer token is supplied. Metrics are aggregate-only and exclude room IDs, peer IDs, usernames, IP addresses, media titles, passwords, and other user-level data.
+
+### Changed
+- Removed `bcryptjs`; temporary room passwords continue to use keyed SHA-256/HMAC hashing as documented.
+- Public room discovery is now rate-limited server-side to one refresh every 10 seconds per socket, with the extension refresh button locked for 11 seconds.
+
+### Fixed
+- Improved Shadow DOM video detection so real embedded players are not hidden by smaller light-DOM preview or placeholder videos.
+- Fixed join-button timeout cleanup after join status responses.
+
+---
+
+## [v2.0.2] — 2026-06-02
+
+### Fixed
+- Peer identity spoofing in relay server: client-supplied `peerId` could be used to impersonate other peers in PEER_STATUS events. Server now always stamps `peerId` with the authenticated sender's identity.
+- Amazon domain detection: replaced broad `includes('amazon.')` substring check with boundary-safe regex that correctly matches all Amazon storefronts (`amazon.com`, `amazon.de`, `amazon.co.uk`, etc.) while rejecting lookalike domains.
+
+---
+
+## [v2.0.1] — 2026-06-01
+
+### Fixed
+- Video detection on Prime Video: `findVideo()` now scores all video elements by size, duration, and mute state instead of picking the first one. Fixes 0×0 placeholder being selected over the actual player.
+- History entries in debug report showing `?` instead of action names.
+- Prime Video status in compatibility matrix updated to reflect partial support.
+
+### Added
+- Multi-video overview table in Copy Debug Report when a page has more than one `<video>` element. Shows resolution, mute state, playback state, readyState, duration, and marks the currently targeted video.
+
+---
+
+## [v2.0.0] — 2026-06-01
+
+### 🌍 Multi-Language Extension (Biggest Feature!)
+- **6-Language UI**: The browser extension is now fully translated into **English, German, French, Spanish, Portuguese (Brazilian), and Russian**. Switch languages instantly in Settings without reload.
+- **Real-Time i18n**: Every label, button, tooltip, toast notification, empty state, and onboarding guide updates dynamically when the language changes.
+
+### New Features
+- **Copy Debug Report (Markdown)**: The *Copy Logs* button in the Status tab now copies a fully formatted Markdown debug report — system info, connection status, video diagnostics, action history, and logs. One click, paste into a GitHub issue, all debugging data ready.
+- **Platform Auto-Detection**: The Dev tab now identifies streaming platforms (YouTube, Netflix, Twitch, Prime Video, Disney+, HBO Max, Vimeo, Dailymotion) and displays the detected platform.
+- **Enhanced Video Debug Info**: 20+ new fields in the Status tab including network state, buffered ranges, dimensions (with 0×0 warning), media error codes, shadow DOM status, seeking/ended/loop flags, volume, playback speed, and data attributes.
+- **No-Video Diagnostic Mode**: When no video is found, the Status tab shows platform, page title, video count, shadow DOM presence, and MediaSession data to help troubleshoot.
+
+### Changed
+- **New TwoPointZero Branding**: Updated extension icons (16/32/48/96/128px).
+- **Larger Popup Logo**: Extension popup icon increased to 48px.
+- **Prime Video Unblocked**: Removed `amazon.` from the tab blacklist so Amazon/Prime Video tabs appear in the video selector.
+- **Improved Debug Report**: Full User-Agent string for accurate browser identification, UTC timestamp, connection details including server URL and room info.
+- **Smart Disconnect**: Improved disconnect handling when leaving rooms.
+- **Human-Readable Room IDs**: Expanded word lists for friendlier room names.
+- **Custom Server Support**: WEB_JOIN_REQUEST and join button for custom server invite flows.
+- **Reconnection Strategy**: Custom server reconnection improvements.
+- **Episode-Aware Sync**: Command sequencing with smarter episode transition detection and echo suppression for smoother series binges.
+- **Sync Status Refinements**: YouTube and Twitch sync behavior improved.
+- **No External Dependencies**: Extension remains dependency-free with no library overhead.
+
+### Fixed
+- Hardcoded strings, missing translation keys, and Service Worker notification race conditions.
+
+---
+
+## Versioning Policy
+
+- **MAJOR** (x.0.0): Breaking protocol changes, architecture rewrites, or major feature milestones.
+- **MINOR** (0.x.0): New features, significant enhancements, new translations, or UI redesigns.
+- **PATCH** (0.0.x): Bug fixes, minor improvements, and documentation updates. PATCH releases may not receive individual changelog entries if bundled with a MINOR release.

docs/HOW_IT_WORKS.md

@@ -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, defaults to a readable adjective-noun pair), `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 (with saved room credentials) or when a saved room configuration exists from a previous session, the background service worker connects to the relay server:
+
+1. **WebSocket Handshake** (on demand): `background.js` opens a WebSocket to `wss://syncserver.koalastuff.net/socket.io/?EIO=4&transport=websocket` only when needed (popup opened or active room).
+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 a keyed SHA-256 HMAC and stores only that 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 keyed SHA-256 HMAC 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`, and `loadeddata`. (Time and volume state are tracked via a 15-second heartbeat interval, not continuous event listeners). 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 synchronized playback.
+
+> **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` | While connected, signals "I'm still connected" and triggers automatic reconnect (500ms base, max 5s). No heartbeats fire when idle (lazy connect). |
+| **Content** | 15 seconds | `content.js` | Sends video metadata: `currentTime`, privacy-filtered `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 title after applying the local media title privacy setting. In episode-only mode this is an identifier such as `S01E04`; when media titles are not sent, the client does not create a new episode lobby.
+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.

docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,104 @@
+# Known Limitations & Accepted Non-Issues (NOFIX)
+
+This file records design decisions that are **intentional** and **out of scope** for
+KoalaSync's threat model. They are frequently re-discovered by reviewers, linters, and
+AI agents and re-reported as "bugs" or "vulnerabilities." They are not. Please read the
+threat model below before flagging any of them.
+
+> **For reviewers & agents:** Do **not** re-report the NOFIX items below. They are
+> deliberate. If you think the *threat model itself* should change (e.g. KoalaSync
+> starts handling accounts, payments, or sensitive data), raise **that** discussion
+> first — these items only stand because the threat model holds.
+
+---
+
+## Threat model
+
+KoalaSync is a **privacy-preserving watch-party sync tool**, not a security product.
+
+- **Rooms are ephemeral.** They exist for a few hours and are auto-reaped. There are no
+  accounts, no persistent storage, no money, and no sensitive content on the relay.
+- **The relay is a zero-persistence, in-memory message bus.** It temporarily holds room
+  and peer state while forwarding play/pause/seek between peers who *chose* to watch
+  together and joined via an invite link shared out-of-band.
+- **Participants are invited.** Anyone in a room was let in. The social contract is
+  "we're watching a video together," not "mutually distrusting parties."
+
+### What we DO defend against
+- **Accidental disruption** — the entire point of Host Control Mode.
+- **Spam / DoS** that degrades the relay for everyone — rate limits, 4 KB payload cap,
+  server-side gating, lazy-cached health responses.
+- **Resource exhaustion / memory leaks** — bounded maps, periodic cleanup, room/peer reaping.
+- **Crashes from malformed input** — strict sanitization and clamping of every field.
+- **Genuine boundary breaches** — admin-metrics auth (constant-time), CORS, WSS upgrade,
+  invite-hash isolation, strict CSP. Reports here are very welcome (see `SECURITY.md`).
+
+### What we explicitly DO NOT defend against
+A **determined participant who modifies their own client to misbehave inside a room they
+were invited to.** The worst they achieve is sending playback commands or seizing the
+"host" role in a temporary room they could already disrupt by other means. That is a
+**social** problem, solved socially: kick them, or start a new room. Engineering real
+identity/auth to prevent it would destroy the account-less, frictionless, privacy-first
+design — a bad trade for an ad-hoc movie night.
+
+---
+
+## NOFIX entries
+
+### NOFIX-1 — `peerId` is unauthenticated; a crafted client can impersonate or seize the host
+**Flag:** `peerId` is client-asserted and broadcast to every peer (in `ROOM_DATA` /
+`PEER_STATUS`). A modified client can join with the host's `peerId`, dedupe-kick the real
+host, and become host — controlling or locking `host-only` mode.
+
+**Why NOFIX:** Requires a *modified client* + an *invited* participant + a `peerId` that is
+only meaningful inside that one *temporary* room. The payoff is sending play/pause or
+locking a room the attacker is already in — pure trolling, instantly reversible (kick /
+new room). Cryptographic per-user identity is wildly disproportionate for an ad-hoc,
+account-less, ephemeral watch party. **Out of threat model.**
+Do **not** "fix" with accounts, signed peerIds, or per-user tokens — that breaks the
+core design.
+
+### NOFIX-2 — Room-password comparison is not constant-time
+**Flag:** room password hashes are compared with `!==` (`server/index.js`), so the compare
+is theoretically timing-attackable.
+
+**Why NOFIX:** The compared value is an **HMAC-SHA256 hash that never leaves the server** —
+an attacker cannot observe it to mount a timing attack. Even a hypothetical success only
+lets someone join a *temporary* room to send playback commands. Not worth defending.
+(The admin-metrics bearer token — a real boundary — **does** use `crypto.timingSafeEqual`.
+That is the line we actually guard.)
+
+### NOFIX-3 — `OFFICIAL_SERVER_TOKEN` is public in the repo
+**Flag:** the connection token in `shared/constants.js` is committed, so anyone can connect.
+
+**Why NOFIX:** It is a **coarse filter** to keep random scanners off the relay, **not
+authentication**. The relay is a public message bus by design; rate limits and per-room
+behavior are the real protections.
+
+### NOFIX-4 — Room IDs are enumerable via `GET_ROOMS`
+**Flag:** any connected client can list all room IDs (and whether each has a password).
+
+**Why NOFIX:** This is the intended **"Public Rooms"** feature. Rooms wanting privacy set a
+password; listing the IDs of password-less rooms only lets someone join a watch party —
+the same as being handed the invite link.
+
+### NOFIX-5 — A pause/seek can only be reverted, not prevented
+**Flag:** in `host-only` mode a guest's pause still fires locally before the extension can
+react, so there is a brief flicker before snap-back.
+
+**Why NOFIX:** A content script cannot intercept a `<video>` event before the element
+acts. Reacting (snap-back) is the only option and is by design; the ~½s flicker is
+acceptable. Not a bug.
+
+---
+
+## Not NOFIX — just deferred (may be revisited)
+
+These are *not* accepted-forever; they are scoped out of v1 and tracked separately
+(see the host-control-mode design docs in `docs/`):
+
+- **Host grace on a long disconnect (EC-10).** A brief reconnect/second-tab keeps the host
+  (handled), but a long real disconnect still falls back to `everyone`. A ~30s host-reserve
+  grace could be added later.
+- **Intent-classifier / snap-back tuning.** Thresholds are first-pass; real-device testing
+  may adjust them.

docs/PRIVACY.md

@@ -0,0 +1,51 @@
+# Privacy Policy
+
+**KoalaSync does not collect, store, or sell any personal data.**
+
+*We don't track you. We only track our server* (relying exclusively on aggregated, anonymous, and non-personal system metrics to monitor performance and stability).
+
+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` and `username`. By default, KoalaSync also shares the selected tab title and media title with the room so peers can identify matching videos and coordinate episode transitions. Privacy Settings let you disable sending the tab title separately, and choose whether media titles are sent in full, reduced to a detected episode identifier (for example `S01E04`), or not sent. Playback metadata (`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 an in-memory **keyed SHA-256 HMAC hash**. The server receives the plaintext password only during join validation, never stores it, and keeps only the hash for the short room lifetime.
+- **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 |
+| Auth failure records (lockout after 5 failed attempts) | 15 minutes | 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 (the extension only stays connected while you are in a room).
+- `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).

docs/PROTOCOL.md

@@ -0,0 +1,369 @@
+# WebSocket Protocol Reference
+
+This document describes the relay behavior implemented by `server/index.js` and
+the event names defined in `shared/constants.js`.
+
+## Transport
+
+- The relay uses Socket.IO v4 events over WebSocket.
+- Long-polling is disabled (`transports: ['websocket']`, `allowUpgrades: false`).
+- Messages are Socket.IO event packets whose payload is an event name plus an
+  object payload.
+- The relay caps incoming Socket.IO message size at 4 KB.
+
+## Connection Handshake
+
+The Socket.IO handshake must include:
+
+- `token`: must match `OFFICIAL_SERVER_TOKEN`.
+- `version`: optional app version. If present, it must be a valid semver-like
+  string and not older than `MIN_VERSION` (default `1.0.0`).
+
+If the token is invalid, the relay emits `error` and disconnects the socket.
+If `version` is invalid or too old, the relay emits `error` and disconnects the
+socket.
+
+After the socket is connected, `join_room` must include `protocolVersion`.
+It must equal `PROTOCOL_VERSION` exactly. A mismatch emits `error` and rejects
+the join attempt; it does not currently disconnect the socket.
+
+## Room Join
+
+### `join_room` (client -> server)
+
+Payload:
+
+```json
+{
+  "roomId": "string, sanitized to [A-Za-z0-9-], max 64",
+  "peerId": "string, max 16",
+  "username": "string, max 30",
+  "password": "string, max 128, optional",
+  "tabTitle": "string, max 100, optional",
+  "mediaTitle": "string, max 100, optional",
+  "protocolVersion": "string, max 16"
+}
+```
+
+Behavior:
+
+- Creates the room if it does not exist and capacity allows it.
+- The first peer becomes `hostPeerId`.
+- Rooms may have an optional password hash.
+- Joining with a duplicate `peerId` disconnects the previous socket for that peer.
+- Joining the same room with the same socket and peer is ignored as a no-op.
+- Switching rooms removes the socket from the old room first.
+
+On success, the joining socket receives `room_data`.
+Other room members receive `peer_status` with `status: "joined"`.
+
+### `room_data` (server -> client)
+
+Payload:
+
+```json
+{
+  "roomId": "string",
+  "peers": ["peer state objects"],
+  "activeLobby": "object or null",
+  "hostPeerId": "string or null",
+  "controlMode": "everyone | host-only",
+  "controllers": ["peerId"],
+  "capabilities": ["host-control", "co-host"]
+}
+```
+
+`room_data` is sent to the joining socket. It is not the general broadcast used
+for every later room update.
+
+## Room Leave
+
+### `leave_room` (client -> server)
+
+Payload: none.
+
+Behavior:
+
+- Rate-limited to 10 events per socket per minute.
+- If the socket is mapped to a room, the relay removes it from that room.
+- Remaining room members receive `peer_status` with `status: "left"` when the
+  peer is no longer represented by another socket.
+- Empty rooms are deleted.
+- If the host leaves and peers remain, the relay assigns the next peer as host,
+  falls back to `controlMode: "everyone"`, resets controllers to the new host,
+  and broadcasts `control_mode`.
+
+Exceeding the `leave_room` limit is logged and the socket is disconnected.
+
+## Relayed Room Events
+
+The relay accepts and sanitizes these events, then emits the same event to other
+peers in the room:
+
+- `play`
+- `pause`
+- `seek`
+- `peer_status`
+- `force_sync_prepare`
+- `force_sync_ack`
+- `force_sync_execute`
+- `episode_lobby`
+- `episode_ready`
+- `episode_lobby_cancel`
+
+Relayed payload fields are sanitized and may include:
+
+```json
+{
+  "senderId": "peerId of sender",
+  "seq": "number",
+  "currentTime": "number 0..86400 or null",
+  "targetTime": "number 0..86400",
+  "playbackState": "playing | paused",
+  "username": "string, max 30",
+  "tabTitle": "string, max 100 or null",
+  "mediaTitle": "string, max 100 or null",
+  "volume": "number 0..1",
+  "muted": "boolean",
+  "desynced": "boolean",
+  "peerId": "sender peerId",
+  "status": "string, max 16",
+  "expectedTitle": "string, max 100",
+  "title": "string, max 100",
+  "actionTimestamp": "number"
+}
+```
+
+Undefined fields are removed before relay. Raw client payloads are not forwarded.
+
+## Media Control
+
+### `play`, `pause`, `seek`
+
+These are room-moving actions. In `host-only` mode, the relay drops them unless
+the sender is a controller.
+
+Common payload fields:
+
+- `currentTime` for `play`/`pause`.
+- `targetTime` for `seek`.
+- `seq` and `actionTimestamp` when the extension needs stale-command or ACK
+  handling.
+
+The content script applies additional client-side filtering for noisy native
+player events before it sends these events.
+
+## Peer Status
+
+### `peer_status`
+
+Used for heartbeats and peer state updates. The extension sends it every
+`HEARTBEAT_INTERVAL` while syncing is active.
+
+Typical fields:
+
+- `peerId`
+- `username`
+- `tabTitle`
+- `mediaTitle`
+- `playbackState`
+- `currentTime`
+- `volume`
+- `muted`
+- `desynced`
+- `status`
+
+The relay stores sanitized peer state and relays the sanitized update to other
+peers.
+
+## Force Sync
+
+Force sync coordination is implemented primarily in the extension. The relay
+sanitizes and relays the events.
+
+### `force_sync_prepare`
+
+Payload includes `targetTime`. The initiator waits for ACKs or for
+`FORCE_SYNC_TIMEOUT` before sending `force_sync_execute`.
+
+In `host-only` mode, only controllers may initiate it.
+
+### `force_sync_ack`
+
+The extension sends ACKs with peer identity and sequence data. The relay relays
+them with the same sanitized relay envelope as other room events, including
+`senderId`.
+
+### `force_sync_execute`
+
+Payload includes `targetTime`. In `host-only` mode, only controllers may send it.
+The relay also allows a matching initiator's execute event after that initiator
+started the prepare step, even if their controller state changed before execute.
+
+## Episode Lobby
+
+Episode lobby coordination is implemented primarily in the extension. The relay
+tracks enough state to include `activeLobby` in `room_data` for later joiners.
+
+### `episode_lobby`
+
+Payload uses `expectedTitle`. The relay creates `activeLobby` when this field is
+present and no lobby is already active.
+
+In `host-only` mode, only controllers may initiate it.
+
+### `episode_ready`
+
+Payload may include `title`. The relay adds the sender to the active lobby's
+ready list when a lobby exists.
+
+### `episode_lobby_cancel`
+
+Clears the active lobby and is relayed to peers. In `host-only` mode, only
+controllers may initiate it.
+
+## Host Control Mode
+
+### `set_control_mode` (client -> server)
+
+Payload:
+
+```json
+{
+  "controlMode": "everyone | host-only"
+}
+```
+
+Only the room host may change the mode. Non-host attempts are ignored and the
+sender receives the current `control_mode` snapshot.
+
+Mode changes are debounced per room with `CONTROL_MODE_MIN_INTERVAL_MS` (500 ms).
+
+### `set_peer_role` (client -> server)
+
+Payload:
+
+```json
+{
+  "peerId": "string, max 16",
+  "controller": "boolean"
+}
+```
+
+Only the room host may promote or demote controllers. The host cannot demote
+themself. Role changes use the same 500 ms per-room debounce as mode changes.
+
+### `control_mode` (server -> client)
+
+Payload:
+
+```json
+{
+  "controlMode": "everyone | host-only",
+  "hostPeerId": "string or null",
+  "controllers": ["peerId"]
+}
+```
+
+Sent when mode or controller state changes, when host migration changes room
+authority, and when unauthorized role/mode attempts need to resync the sender.
+
+## Room List
+
+### `get_rooms` (client -> server)
+
+Payload: none.
+
+No admin token is required for this Socket.IO event.
+
+Limits:
+
+- Counts against the per-socket event limit.
+- Also has a 10 second per-socket cooldown.
+
+### `room_list` (server -> client)
+
+Payload:
+
+```json
+{
+  "rooms": [
+    {
+      "id": "room id",
+      "peerCount": 2,
+      "hasPassword": false
+    }
+  ]
+}
+```
+
+## Ping, Pong, and ACK
+
+### `ping`
+
+Payload:
+
+```json
+{
+  "t": 1234567890,
+  "target": "peerId, optional"
+}
+```
+
+If `target` is omitted, the relay responds to the sender with `pong`.
+If `target` is another peer in the same room, the relay sends `ping` to that peer
+with `{ "t": ..., "sender": "senderPeerId" }`.
+
+### `pong`
+
+Payload:
+
+```json
+{
+  "t": 1234567890,
+  "target": "peerId, optional"
+}
+```
+
+If `target` is a peer in the same room, the relay sends `pong` to that peer with
+`{ "t": ... }`.
+
+### `event_ack`
+
+Client payload:
+
+```json
+{
+  "targetId": "peerId",
+  "actionTimestamp": 1234567890
+}
+```
+
+If sender and target are still in the same room, the relay emits:
+
+```json
+{
+  "senderId": "sender peerId",
+  "actionTimestamp": 1234567890
+}
+```
+
+## Rate Limits
+
+- Connections: 10 per IP per minute; excess connections are disconnected.
+- Relayed/events: 50 per socket per 10 seconds; excess disconnects the socket.
+- `get_rooms`: 10 second cooldown per socket plus the event limit.
+- `leave_room`: 10 per socket per minute; excess disconnects the socket.
+- Invalid room passwords: tracked per IP and room. Five recent failures block
+  more password attempts for that room until the failure window ages out.
+- HTTP health and admin-metrics endpoints have their own rate limits outside this
+  Socket.IO protocol.
+
+## Capabilities
+
+`room_data.capabilities` advertises server-backed features:
+
+- `host-control`
+- `co-host`
+
+Clients should treat a missing or unknown capabilities list as unsupported.

docs/README.md

@@ -0,0 +1,40 @@
+# Technical Documentation
+
+This directory contains deep-dives into the KoalaSync protocol, architecture, roadmap, and operational guidelines.
+
+## Start Here by Role
+
+- **Users and reviewers**: Start with [HOW_IT_WORKS.md](HOW_IT_WORKS.md), then [PRIVACY.md](PRIVACY.md) and [TESTED_SERVICES.md](TESTED_SERVICES.md).
+- **Self-hosters**: Start with the root [README.md](../README.md), then [devops.md](devops.md), [PROTOCOL.md](PROTOCOL.md), and the examples in `../examples/`.
+- **Contributors**: Start with [../CONTRIBUTING.md](../CONTRIBUTING.md), then [ARCHITECTURE.md](ARCHITECTURE.md), [SYNC_GUIDE.md](SYNC_GUIDE.md), and the README for the subdirectory you are editing.
+- **AI agents**: Start with [AI_INIT.md](AI_INIT.md), then read the relevant subdirectory README before changing files.
+- **Security reviewers**: Start with [SECURITY.md](../SECURITY.md), [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md), [PRIVACY.md](PRIVACY.md), and [PROTOCOL.md](PROTOCOL.md).
+
+## 🏗️ Core Architecture & Design
+
+- **[ARCHITECTURE.md](ARCHITECTURE.md)**: Overview of the communication flows, Dual Heartbeat architecture, and synchronization logic.
+- **[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.
+- **[host-control-mode.md](host-control-mode.md)**: Design, requirements, and edge cases of the Host Control feature.
+- **[AI_INIT.md](AI_INIT.md)**: Maintainer and AI-agent onboarding: non-negotiables, workflow order, and safety checks.
+
+## 📡 Protocol & Synchronization
+
+- **[PROTOCOL.md](PROTOCOL.md)**: Low-level message format and payload descriptions for the KoalaSync sync protocol.
+- **[SYNC_GUIDE.md](SYNC_GUIDE.md)**: Guide on keeping protocol constants synchronized across the workspace.
+
+## 📋 Compatibility, Roadmap & Contribution
+
+- **[TESTED_SERVICES.md](TESTED_SERVICES.md)**: Status of compatibility with major streaming services and contribution guidelines for testing new platforms.
+- **[KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md)**: Threat model and accepted design limitations (NOFIX entries) for security audits.
+- **[PRIVACY.md](PRIVACY.md)**: Privacy model and data-handling policy for users, reviewers, and contributors.
+- **[ROADMAP.md](ROADMAP.md)**: Planned features, backlog items, and rejected proposals.
+- **[TRANSLATION.md](TRANSLATION.md)**: Guide for native speakers to contribute and audit dynamic extension/website translations.
+
+## 🚀 DevOps & Releases
+
+- **[devops.md](devops.md)**: Guide on the automated tag-based release pipeline.
+- **[CHANGELOG.md](CHANGELOG.md)**: Detailed history of releases and changes.
+
+---
+
+*For high-level project information and developer setup instructions, refer to the root [README.md](../README.md).*

docs/ROADMAP.md

@@ -0,0 +1,88 @@
+# KoalaSync Roadmap
+
+> Feature priorities, planned work, backlog, and rejected ideas for KoalaSync.
+
+---
+
+## Status Legend
+
+| Badge | Meaning |
+|---|---|
+| 🚧 In Progress | Currently being developed |
+| 📋 Planned | Prioritized for an upcoming phase |
+| 💡 Backlog | Under evaluation, not yet prioritized |
+| ❌ Rejected | Declined (with rationale) |
+| ✅ Completed | Shipped |
+
+---
+
+## 🚧 In Progress
+
+*Currently being worked on.*
+
+| Feature | Priority | Area |
+|---|---|---|
+| *(none yet)* | | |
+
+---
+
+## 📋 Planned
+
+*Prioritized for upcoming phases.*
+
+### 2. Invite link with target URL for auto-redirect
+
+- **Priority:** P2
+- **Category:** UX / Ease of Sharing
+- **Background:** The invite link currently only contains the room ID. The invited person has to manually open the page. Ideally, the link would include the shared tab's URL so the invitee gets redirected to the right page and the tab is auto-selected (auto-matching via tab title already exists).
+- **Known challenges:**
+  - Many streaming sites (e.g., Emby, Jellyfin) don't have unique URLs per content — once inside the player, the URL stays the same.
+  - Dozens of such edge cases exist; a generic solution is difficult.
+  - Would likely need site-specific extractor logic (similar to the existing sync service adapters).
+- **Possible approaches:**
+  - Fallback: if no unique URL can be determined, only pass the tab title.
+  - Site-specific URL extraction for known services.
+
+---
+
+## 💡 Backlog
+
+*Ideas and feature requests under evaluation.*
+
+### In-room chat overlay (like TeleParty)
+
+- **Priority:** P3
+- **Category:** Social / Communication
+- **Background:** A collapsible chat panel to the right of the video (or as an overlay) allowing text-based communication with everyone in the room.
+- **Why backlog (still uncertain):**
+  - **Use case:** No strong personal need — with chat, latency matters less than with voice; async communication tolerates a few seconds of delay.
+  - **Complexity:** Relatively large feature (UI + message persistence + possibly history).
+  - **Legal/moderation:** Unclear what moderation requirements would apply if users can exchange chat messages. Could be relevant depending on jurisdiction.
+- **Status:** Under evaluation, may come later.
+
+### Cross-frame video detection and control
+
+- **Priority:** P3
+- **Category:** Compatibility / Embedded Players
+- **Background:** KoalaSync currently injects on demand into the selected tab's top frame. This works for normal top-frame players, including current Emby/Jellyfin usage, but does not cover cases where the real `<video>` lives inside a cross-origin iframe or an `about:blank`/`srcdoc` player frame.
+- **Possible approach:** Add an opt-in frame bridge where child frames announce detected videos to the top frame, and the top frame routes remote play/pause/seek commands to the active child video.
+- **Status:** Future compatibility work, not needed for current Emby behavior.
+
+### Local extension E2E smoke tests
+
+- **Priority:** P2
+- **Category:** Testing / Release Confidence
+- **Background:** The release verification covers unit tests, server integration, syntax, lint, audits, and builds, but it does not currently run a real browser extension flow. A small local E2E smoke suite would catch regressions in content-script injection, tab navigation reinjection, remote seek handling, and iframe player support.
+- **Possible approach:** Add a separate local-only Playwright smoke command that loads the unpacked extension, opens two controlled video pages, and verifies play/pause/seek through the actual extension path. Keep it outside `npm run verify` until it is stable enough for CI.
+- **Status:** Backlog, recommended before larger content-script or frame-bridge changes.
+
+---
+
+## ❌ Rejected
+
+*Declined features with rationale — keeps decisions documented so they don't get re-debated.*
+
+| Feature | Reason |
+|---|---|
+| *(none yet)* | |
+

docs/SYNC_GUIDE.md

@@ -0,0 +1,41 @@
+# 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. **After modifying** `shared/names.js`.
+5. **Before committing** changes to the repository if any shared protocol or extension-mirrored files were touched.
+6. **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.cjs
+# or simply:
+npm run build:extension
+```
+
+## What does it do?
+The build script performs the following actions:
+1. Synchronizes shared files by copying `shared/constants.js`, `shared/blacklist.js`, `shared/names.js`, and `shared/README.md` into `extension/shared/`.
+2. Injects `EVENTS`, `HEARTBEAT_INTERVAL`, and `episode-utils.js` functions (`extractEpisodeId`, `sameEpisode`) into `content.js` via marker-based replacement.
+3. Injects browser-specific uninstall URL constants into `background.js` and a build timestamp into `popup.html`.
+4. Compiles browser-specific manifest files.
+5. 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.
+- **Never 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. Run the build script to synchronize other constant updates.
+
+> [!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.

docs/TESTED_SERVICES.md

@@ -0,0 +1,66 @@
+# 🎬 Tested Streaming Services & Compatibility
+
+This document tracks which streaming platforms and media servers are supported by the KoalaSync extension. 
+
+> [!TIP]
+> **Contributions are highly welcome!** 🤝 Anyone can easily update this list. If you have tested a streaming service (whether it works, has issues, or is not yet listed), please help the project by submitting a quick Pull Request. See the [How to Contribute](#how-to-contribute) guide below!
+
+---
+
+## Compatibility Matrix
+
+| Service | Sync Works | Media Title | Episode Auto-Sync | Last Tested | Tested By | Extension Version | Notes |
+| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :--- |
+| **YouTube** | ✅ Full | ✅ Full | ❌ N/A | — | — | — | Individual videos, not episodes. |
+| **Twitch** | ✅ Full | ✅ Full | ❌ N/A | — | — | — | Individual streams/VODs. |
+| **Netflix** | ✅ Full | ❌ | ❌ | — | — | — | No media title exposed. |
+| **Emby** | ✅ Full | ✅ Full | ✅ Full | — | — | — | Best-in-class support. |
+| **Jellyfin** | ✅ Full | ✅ Full | ✅ Full | — | — | — | — |
+| **Plex** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Disney+** | ✅ Full | ⚠️ Partial | ❌ | — | — | — | Series title only (e.g. "The Simpsons"), no episode info. |
+| **Prime Video** | ✅ Full  | ✅ Full  | ❌ | — | — | — | — |
+| **HBO Max / Max** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Crunchyroll** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Vimeo** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Dailymotion** | Not tested | Not tested | Not tested | — | — | — | — |
+| **ARD / ZDF Mediathek** | Not tested | Not tested | Not tested | — | — | — | — |
+| **Vix** | ✅ Full | ✅ Full | ✅ Full | — | — | — | Everything works correctly. |
+
+### Legend
+
+| Symbol | Meaning |
+| :---: | :--- |
+| ✅ Full | Works without limitations. |
+| ⚠️ Partial | Works with caveats (see Notes). |
+| ❌ | Not supported / does not work. |
+| ❌ N/A | Not applicable (feature does not exist on the platform). |
+| **Not tested** | Has not been tested yet. |
+
+---
+
+## How to Contribute
+
+Updating this compatibility list is quick and easy! You don't need deep coding skills to contribute:
+
+1. **Fork the Repository**: Click the **Fork** button at the top of the [KoalaSync GitHub Repository](https://github.com/Shik3i/KoalaSync).
+2. **Edit this File**: Open [docs/TESTED_SERVICES.md](TESTED_SERVICES.md) in your fork's browser editor (or clone it locally) and update the table with your testing details.
+3. **Commit & Push**: Commit your changes with a clear message (e.g., `docs: update Netflix compatibility status`).
+4. **Create a Pull Request**: Submit the Pull Request (PR) from your fork to our `main` branch.
+
+> [!NOTE]
+> **Reporting Problems:** If you notice a bug or partial support on a service, please open a [GitHub Issue](https://github.com/Shik3i/KoalaSync/issues) describing the problem, and link it in the **Notes** column of the table. 
+> 
+> _If you are unsure how to create/link an issue, don't worry! Simply submit the PR anyway, and the maintainers will gladly create and link the issue for you._
+
+---
+
+## Technical Background
+
+KoalaSync works on any website with a **standard HTML5 `<video>` element** that allows script injection. 
+
+Limited functionality on certain platforms is typically caused by:
+- **DRM/Copy Protection** (e.g., Widevine on Netflix) which restricts access to media metadata like title and playback state
+- **Shadow DOM encapsulation** that hides video elements from content scripts
+- **Strict Content Security Policies** (CSP) that block script injection
+
+Websites with heavily obfuscated custom players (e.g., complex Shadow DOM, iframe isolation) may require platform-specific workarounds in `content.js`.

docs/TRANSLATION.md

@@ -0,0 +1,121 @@
+# KoalaSync Translation & Localization Guide
+
+Welcome to the **KoalaSync** translation guide. We rely on the open-source community to make KoalaSync accessible to users worldwide.
+
+KoalaSync is split into two independent translation areas. You can translate either one, or both:
+
+1. **The Browser Extension** (`extension/locales/`): The core product that users interact with daily.
+2. **The Website** (`website/locales/`): The landing page and invitation bridge.
+
+---
+
+## Supported Languages Dashboard
+
+We divide supported languages into two tiers: **Core Languages** (fully hand-crafted and audited by native speakers) and **Extended Languages** (auto-generated using translation models to expand initial coverage).
+
+> [!TIP]
+> **Help Us Improve!**
+> We welcome community contributions to audit `Auto-Generated` translations and elevate them to `100% Manually Verified` status.
+
+| Language Code | Language Name | Verification Status | Rationale / Context |
+| :--- | :--- | :--- | :--- |
+| `en` | **English** | `100% Manually Verified` | Global default language (verified by developer) |
+| `de` | **German** | `100% Manually Verified` | Developer's native language |
+| `fr` | **French** | `Auto-Generated` | Needs manual native review and polishing |
+| `es` | **Spanish** | `100% Manually Verified` | Manual native review by Alenia Studios |
+| `pt-BR` | **Portuguese (Brazil)** | `100% Manually Verified` | Manual native review by Alenia Studios |
+| `ru` | **Russian** | `Auto-Generated` | Needs manual native review and polishing |
+| `it` | **Italian** | `100% Manually Verified` | Manual native review by Alenia Studios |
+| `pl` | **Polish** | `Auto-Generated` | Needs manual native review and polishing |
+| `tr` | **Turkish** | `Auto-Generated` | Needs manual native review and polishing |
+| `nl` | **Dutch** | `Auto-Generated` | Needs manual native review and polishing |
+| `ja` | **Japanese** | `Auto-Generated` | Needs manual native review and polishing |
+| `ko` | **Korean** | `Auto-Generated` | Needs manual native review and polishing |
+| `pt` | **European Portuguese** | `100% Manually Verified` | Manual native review by Alenia Studios |
+| `zh` | **Chinese (Simplified)** | `Auto-Generated` | Needs manual native review and polishing |
+| `uk` | **Ukrainian** | `Auto-Generated` | Needs manual native review and polishing |
+
+> [!WARNING]
+> **Autogeneration Quality Rule**
+> Any newly contributed languages must be marked as `Auto-Generated` in this table until fully reviewed and signed off by a native speaker in a pull request.
+
+---
+
+## How to Translate KoalaSync
+
+Here is the exact step-by-step process for contributing translations.
+
+### Step 1: Fork and Clone the Repository
+
+If you are an external contributor, start with the standard open-source workflow:
+
+1. Click the "Fork" button on GitHub to create your own copy of the repository.
+2. Clone your fork locally: `git clone https://github.com/YOUR-USERNAME/KoalaSync.git`
+3. Create a branch: `git checkout -b translation/my-language`
+
+### Step 2: Translate the Extension
+
+The browser extension handles real-time syncing, settings, and popups.
+
+1. Navigate to `extension/locales/`.
+2. Edit an existing `[lang].json` or copy `en.json` to create a new one (for example, `it.json`).
+3. Translate all string values. **Do not change the JSON keys.**
+
+### Step 3: Translate the Website
+
+The website hosts the landing page and invitation bridge.
+
+1. Navigate to `website/locales/`.
+2. Edit an existing `[lang].json` or copy `en.json` to create a new one.
+3. Translate all string values. **Do not change the JSON keys.**
+4. If creating a brand new language, configure the metadata at the top of your JSON file:
+
+```json
+{
+  "LANG_CODE": "it",
+  "HTML_CLASS": "lang-it",
+  "CANONICAL_PATH": "it/",
+  "LANG_TOGGLE_URL": "../",
+  "LANG_TOGGLE_TEXT": "EN"
+}
+```
+
+5. If creating a brand new language, register it in `website/build.cjs` by adding it to the `languages` array.
+
+### Step 4: Verify Locally
+
+Ensure your JSON files are valid and all keys match the English baseline. Open your terminal in the KoalaSync root folder and run:
+
+```bash
+# Tests the extension locales for missing keys or syntax errors
+node scripts/test-locales.cjs
+
+# Tests the website locales for missing keys or syntax errors
+node scripts/test-website-locales.mjs
+
+# Builds the website with your new translations
+node website/build.cjs
+```
+
+If you receive any errors about missing keys or placeholder strings, fix them before submitting.
+
+### Step 5: Commit and Pull Request
+
+1. Open this `TRANSLATION.md` file and add or update your language in the **Supported Languages Dashboard** above. Mark it as `100% Manually Verified` only if it has been reviewed by a native speaker.
+2. Commit your changes: `git commit -m "Update Italian translations"`
+3. Push to your fork: `git push origin translation/my-language`
+4. Open a pull request on the main KoalaSync repository on GitHub.
+
+---
+
+## Strict Legal Exclusion Rule
+
+Our legal pages have strict constraints to protect user privacy and avoid regulatory liabilities.
+
+> [!IMPORTANT]
+> **Do Not Translate Legal Documents**
+> The legal notice (`website/impressum.html`) and privacy policy (`website/datenschutz.html`) **MUST remain exclusively in English and German**.
+>
+> **Rationale:** Legal compliance under the European Union General Data Protection Regulation (GDPR) and the German Digital Services Act (DDG). Offering automated translations of legally binding notices introduces compliance risks due to potential mistranslations of liability limits.
+>
+> **Technical fallback:** Our system automatically falls back to English for legal pages if a user visits them in an unsupported language, so you do not need to translate them.

docs/devops.md

@@ -0,0 +1,51 @@
+# DevOps Release Workflow
+
+This document describes the deployment and release process for KoalaSync.
+
+## Tag-Based Releases
+
+KoalaSync uses a fully automated release pipeline triggered by Git tags. 
+
+> [!IMPORTANT]
+> **DO NOT** manually bump the version numbers in any files (such as `package.json`, `manifest.base.json`, `shared/constants.js`, etc.) before creating a release. 
+> Bumping versions manually is redundant, leads to conflicts, and is completely handled by the CI/CD pipeline.
+
+### How it Works
+
+When you push a Git tag matching `v*` (e.g., `v2.5.1`), the GitHub Actions release workflow (`.github/workflows/release.yml`) is triggered. The workflow performs the following actions:
+
+1. **Extracts the version** from the tag (e.g., `2.5.1` from `v2.5.1`).
+2. **Injects the version** automatically into the following files:
+   - `extension/manifest.base.json`
+   - `shared/constants.js` (updates `APP_VERSION`)
+   - `package.json`
+   - `website/version.json`
+   - `website/template.html` (updates `softwareVersion` schema)
+   - `README.md` (updates badge and announcement banner)
+   - `website/sitemap.xml` (updates `lastmod` dates)
+3. **Commits and pushes** these version updates back to the `main` branch automatically with the commit message `chore(release): update versions to vX.X.X [skip ci]`.
+4. **Builds the extension** for both Chrome and Firefox and publishes the zipped archives.
+5. **Builds the website** and uploads website artifacts.
+6. **Builds and publishes** the Docker image for the relay server to the GitHub Container Registry (`ghcr.io`).
+
+---
+
+## Steps to Deploy a New Release
+
+To release a new version (e.g., `v2.5.1`), follow these steps:
+
+1. Make sure your local repository is synced on `main`:
+   ```bash
+   git checkout main
+   git pull origin main
+   ```
+2. Create a local Git tag:
+   ```bash
+   git tag v2.5.1
+   ```
+3. Push the tag to GitHub:
+   ```bash
+   git push origin v2.5.1
+   ```
+
+The release pipeline will take care of the rest! You can monitor the progress under the **Actions** tab of the GitHub repository.

docs/host-control-mode.md

@@ -0,0 +1,151 @@
+# Host Control Mode
+
+This document describes the Host Control Mode implementation in the relay and
+extension. It only covers behavior implemented in the current codebase.
+
+## Modes
+
+### `everyone`
+
+- Default room mode.
+- Any peer may send room-moving playback events.
+
+### `host-only`
+
+- Only controllers may send room-moving playback events.
+- The host is always a controller.
+- The host can promote additional peers to controllers.
+- Guests can keep watching locally in solo/desynced mode, but their local actions
+  still do not drive the shared room.
+
+Room-moving events are:
+
+- `play`
+- `pause`
+- `seek`
+- `force_sync_prepare`
+- `force_sync_execute`
+- `episode_lobby`
+- `episode_lobby_cancel`
+
+Heartbeats, force-sync ACKs, episode-ready events, ping/pong, and command ACKs
+remain allowed for guests.
+
+## Server State
+
+Rooms store Host Control state in memory:
+
+```js
+{
+  hostPeerId,
+  controlMode,
+  controllers,
+  lastControlModeChangeAt,
+  lastRoleChangeAt,
+  forceSyncInitiator
+}
+```
+
+`controllers` is a `Set` on the server and is serialized as an array in
+`room_data` and `control_mode`.
+
+State is not persisted across relay restarts.
+
+## Authority Rules
+
+### Changing mode
+
+Only `hostPeerId` may send `set_control_mode`.
+
+Valid values:
+
+- `everyone`
+- `host-only`
+
+Invalid values are ignored. Non-host attempts are ignored and the sender receives
+the current `control_mode` snapshot so optimistic UI can revert.
+
+Mode changes are debounced per room for 500 ms.
+
+### Promoting and demoting controllers
+
+Only `hostPeerId` may send `set_peer_role`.
+
+The host cannot demote themself. No-op role changes are ignored. Role changes are
+debounced per room for 500 ms.
+
+### Host leaving
+
+When the host leaves and peers remain:
+
+- the next peer becomes `hostPeerId`;
+- `controlMode` falls back to `everyone`;
+- `controllers` is reset to the new host;
+- the relay broadcasts `control_mode`.
+
+When a non-host controller leaves, the relay removes that peer from
+`controllers` and broadcasts `control_mode`.
+
+## Enforcement
+
+The implementation has two enforcement points:
+
+- The extension background script blocks local guest attempts in `host-only` and
+  sends `HOST_BLOCKED` to the content script for local UX.
+- The relay drops room-moving events from non-controllers in `host-only`, so old
+  or modified clients cannot drive the room.
+
+The relay is the authority for room-wide effects.
+
+## Guest UX
+
+When a guest action is blocked locally, the content script classifies it:
+
+- deliberate user action: show the host-control dialog;
+- likely involuntary player action (buffering, tab refocus, no recent gesture):
+  silently snap back when safe;
+- live/DVR stream: degrade without forcing snap-back.
+
+The dialog offers:
+
+- stay in sync: resync to the host;
+- watch on my own: enter solo/desynced mode.
+
+In solo/desynced mode:
+
+- the guest can control their local video;
+- host room commands are ignored locally, except force-sync preparation is ACKed
+  so the host's flow can continue;
+- the guest can resync to the host.
+
+The extension reports `desynced` in peer status so the host UI can show that a
+guest is watching solo.
+
+## Force Sync Edge Case
+
+The relay tracks `forceSyncInitiator` after a controller sends
+`force_sync_prepare`.
+
+This allows that same initiator's `force_sync_execute` through even if their
+controller role changes before execute arrives. Without this, a demotion in the
+middle of a force-sync flow could leave peers waiting after prepare.
+
+The relay clears `forceSyncInitiator` after execute or when the initiator leaves.
+
+## Capabilities
+
+The relay advertises Host Control support in `room_data.capabilities`:
+
+- `host-control`
+- `co-host`
+
+The extension hides or disables matching UI when capabilities are missing.
+
+## Related Events
+
+See [PROTOCOL.md](PROTOCOL.md) for payloads and relay behavior for:
+
+- `set_control_mode`
+- `control_mode`
+- `set_peer_role`
+- host-only gated relay events

eslint.config.mjs

@@ -0,0 +1,85 @@
+import noUnsanitized from "eslint-plugin-no-unsanitized";
+
+export default [
+  {
+    ignores: ["coverage/**", "dist/**", "node_modules/**", "scratch/**", "website/www/**"]
+  },
+  {
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+      globals: {
+        chrome: "readonly",
+        browser: "readonly",
+        window: "readonly",
+        document: "readonly",
+        navigator: "readonly",
+        console: "readonly",
+        localStorage: "readonly",
+        setTimeout: "readonly",
+        setInterval: "readonly",
+        clearTimeout: "readonly",
+        clearInterval: "readonly",
+        requestAnimationFrame: "readonly",
+        cancelAnimationFrame: "readonly",
+        fetch: "readonly",
+        CustomEvent: "readonly",
+        MutationObserver: "readonly",
+        IntersectionObserver: "readonly",
+        Uint32Array: "readonly",
+        Set: "readonly",
+        Map: "readonly",
+        Promise: "readonly",
+        Array: "readonly",
+        Object: "readonly",
+        JSON: "readonly",
+        Math: "readonly",
+        Number: "readonly",
+        String: "readonly",
+        Date: "readonly",
+        Error: "readonly",
+        URL: "readonly",
+        URLSearchParams: "readonly",
+        WebSocket: "readonly",
+        history: "readonly",
+        location: "readonly",
+        self: "readonly",
+        process: "readonly",
+      }
+    },
+    plugins: {
+      "no-unsanitized": noUnsanitized
+    },
+    rules: {
+      // Mirrors the AMO validator's "Unsafe assignment to innerHTML" check, so a
+      // rejection at upload time surfaces here instead.
+      "no-unsanitized/property": "error",
+      "no-unsanitized/method": "error",
+      "no-undef": "error",
+      "no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_", "caughtErrorsIgnorePattern": "^_" }],
+      "no-unreachable": "error",
+      "no-constant-condition": "error",
+      "no-dupe-keys": "error",
+      "no-duplicate-case": "error",
+      "no-empty": "error",
+      "no-extra-semi": "error",
+      "no-prototype-builtins": "warn",
+      "no-unsafe-optional-chaining": "error",
+      "valid-typeof": "error"
+    }
+  },
+  {
+    files: ["server/**/*.js", "scripts/**/*.js", "scripts/**/*.cjs", "website/build.cjs", "website/**/*.cjs"],
+    languageOptions: {
+      globals: {
+        require: "readonly",
+        __dirname: "readonly",
+        __filename: "readonly",
+        process: "readonly",
+        module: "readonly",
+        exports: "readonly",
+        Buffer: "readonly"
+      }
+    }
+  }
+];

examples/Caddyfile.example

@@ -0,0 +1,99 @@
+# ==============================================================================
+# KoalaSync - Production Caddy Configuration Example
+# ==============================================================================
+# This file provides examples of both a lightweight "Simple" configuration 
+# and a production-hardened "Advanced" configuration.
+# Replace domains, reverse proxy locations, and directories with your actual setup.
+
+# ------------------------------------------------------------------------------
+# OPTION A: Simple Configuration
+# ------------------------------------------------------------------------------
+# Minimal configuration that serves the static website, enables gzip compression,
+# supports extension-less Clean URLs, and reverse proxies the relay server.
+
+# sync.koalastuff.net {
+#     root * /var/www/koalasync/website/www
+#     encode zstd gzip
+#
+#     # Clean URLs support (resolves /join to join.html, etc.)
+#     try_files {path} {path}.html {path}/
+#     file_server
+#
+#     # Serve the themed 404 page for unknown URLs (without this block,
+#     # Caddy returns an empty 404 response)
+#     handle_errors {
+#         @notfound expression {err.status_code} == 404
+#         rewrite @notfound /404.html
+#         file_server
+#     }
+# }
+#
+# syncserver.koalastuff.net {
+#     reverse_proxy localhost:3000
+# }
+
+
+# ------------------------------------------------------------------------------
+# OPTION B: Advanced Configuration (Production-Hardened)
+# ------------------------------------------------------------------------------
+# Highly secure, optimized configuration using advanced HTTP security headers,
+# aggressive static assets caching, server signature concealment, and strict 
+# hardware permission access policies.
+
+(security_headers) {
+	header {
+		# Enable HTTP Strict Transport Security (HSTS)
+		Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+		# Prevent clickjacking attacks (Sameorigin)
+		X-Frame-Options "SAMEORIGIN"
+		# Prevent MIME-sniffing
+		X-Content-Type-Options "nosniff"
+		# Enable browser XSS protection
+		X-XSS-Protection "1; mode=block"
+		# Control referrer information
+		Referrer-Policy "strict-origin-when-cross-origin"
+		# Hide Caddy server stamp signature
+		-Server
+	}
+}
+
+sync.koalastuff.net {
+    encode zstd gzip
+    root * /var/www/koalasync/website/www
+
+    # Clean URLs: Resolves paths without .html in the URL
+    try_files {path} {path}.html {path}/
+    file_server
+
+    # Serve the themed 404 page for unknown URLs (without this block,
+    # Caddy returns an empty 404 response)
+    handle_errors {
+        @notfound expression {err.status_code} == 404
+        rewrite @notfound /404.html
+        file_server
+    }
+
+    # Static Caching for high-performance PageSpeed (1 year with validation)
+    @static {
+        file
+        path *.ico *.css *.js *.png *.svg *.webp *.avif
+    }
+    header @static Cache-Control "public, max-age=31536000, must-revalidate"
+
+    # Security Headers & Content Security Policy (CSP)
+    import security_headers
+    header {
+        # CSP hardened with base-uri and form-action limits
+        Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; object-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none';"
+        
+        # Modern Permissions Policy (blocks browser hardware access for enhanced privacy)
+        Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()"
+    }
+}
+
+syncserver.koalastuff.net {
+	import security_headers
+	encode zstd gzip
+	reverse_proxy KoalaSync:3000
+}
+

examples/docker-compose.caddy.example.yml

@@ -0,0 +1,19 @@
+services:                                                                                # Top-level key defining all containers in this Compose file
+  koala-sync:                                                                              # Name of the KoalaSync service
+    image: ghcr.io/shik3i/koalasync:latest                                                 # Pulls the latest KoalaSync image from GitHub Container Registry
+    container_name: KoalaSync                                                              # Sets a fixed container name instead of an auto-generated one
+    restart: always                                                                        # Always restart the container if it stops or if Docker starts
+    environment:                                                                           # Environment variables passed into the container
+      - TZ=Europe/Berlin                                                                   # Sets the timezone inside the container
+      - PORT=3000                                                                          # Port KoalaSync listens on inside the container
+      - MIN_VERSION=1.0.0                                                                  # Minimum client version allowed to connect
+      - MAX_ROOMS=100                                                                      # Maximum number of rooms that can exist
+      - MAX_PEERS_PER_ROOM=25                                                              # Maximum number of peers allowed per room
+      - SERVER_SALT=CHANGE_ME_GENERATE_WITH_OPENSSL_RAND_BASE64_32                         # Required: unique random salt for room-password hashes
+      - ADMIN_METRICS_TOKEN=                                                               # Optional: 32+ char random token for aggregate-only /health metrics
+    pids_limit: 2048                                                                       # Limits the container to 2048 process IDs for safety
+    networks:                                                                              # Attaches the service to the networks listed below
+      - caddy_net                                                                          # Joins the pre-existing Caddy network for reverse proxying
+networks:                                                                                  # Top-level networks definition
+  caddy_net:                                                                                # Network name as referenced by the service
+    external: true                                                                          # Marks the network as managed outside of Compose (created by Caddy)

examples/docker-compose.ip.example.yml

@@ -0,0 +1,23 @@
+services:                                                                                # Top-level key defining all containers in this Compose file
+  koala-sync:                                                                              # Name of the KoalaSync service
+    image: ghcr.io/shik3i/koalasync:latest                                                 # Pulls the latest KoalaSync image from GitHub Container Registry
+    container_name: KoalaSync                                                              # Sets a fixed container name instead of an auto-generated one
+    restart: always                                                                        # Always restart the container if it stops or if Docker starts
+    ports:                                                                                 # Exposes the container port to the host
+      - "3000:3000"                                                                        # Maps host port 3000 to container port 3000
+    environment:                                                                           # Environment variables passed into the container
+      - TZ=Europe/Berlin                                                                   # Sets the timezone inside the container
+      - PORT=3000                                                                          # Port KoalaSync listens on inside the container
+      - MIN_VERSION=1.0.0                                                                  # Minimum client version allowed to connect
+      - MAX_ROOMS=100                                                                      # Maximum number of rooms that can exist
+      - MAX_PEERS_PER_ROOM=25                                                              # Maximum number of peers allowed per room
+      - SERVER_SALT=CHANGE_ME_GENERATE_WITH_OPENSSL_RAND_BASE64_32                         # Required: unique random salt for room-password hashes
+      - ADMIN_METRICS_TOKEN=                                                               # Optional: 32+ char random token for aggregate-only /health metrics
+    pids_limit: 2048                                                                       # Limits the container to 2048 process IDs for safety
+    networks:                                                                              # Attaches the service to the networks listed below
+      bond0_network:                                                                       # Network name as referenced by the service
+        ipv4_address: 192.168.1.XXX                                                        # Static IPv4 address for the KoalaSync container
+networks:                                                                                  # Top-level networks definition
+  bond0_network:                                                                          # Network name inside Compose
+    external: true                                                                        # Marks the network as managed outside of Compose
+    name: bond0                                                                           # Name of the pre-existing network on the Docker host

examples/json_exporter.example.yml

@@ -0,0 +1,104 @@
+# Prometheus Community JSON Exporter Configuration Example
+# File: examples/json_exporter.example.yml
+#
+# Use this configuration to map KoalaSync admin health metrics (JSON)
+# to native Prometheus metrics.
+#
+# Usage:
+# 1. Rename this file to json_exporter.yml
+# 2. Replace "YOUR_ADMIN_METRICS_TOKEN" with your actual ADMIN_METRICS_TOKEN env value
+# 3. Mount it to the json-exporter docker container: /config.yml
+
+modules:
+  koalasync:
+    http_client_config:
+      bearer_token: "YOUR_ADMIN_METRICS_TOKEN"
+    metrics:
+      - name: koalasync_uptime_seconds
+        path: '{.uptime}'
+        help: "Uptime of the KoalaSync relay server in seconds"
+
+      - name: koalasync_rooms
+        path: '{.rooms}'
+        help: "Total active rooms"
+
+      - name: koalasync_connections
+        path: '{.connections}'
+        help: "Total active socket connections (sockets)"
+
+      - name: koalasync_peers
+        path: '{.peers}'
+        help: "Total connected peers across all rooms"
+
+      - name: koalasync_rooms_with_lobby
+        path: '{.roomsWithLobby}'
+        help: "Number of rooms waiting in an episode lobby"
+
+      - name: koalasync_avg_peers_per_room
+        path: '{.avgPeersPerRoom}'
+        help: "Average number of peers per room"
+
+      - name: koalasync_max_peers_in_room
+        path: '{.maxPeersInRoom}'
+        help: "Maximum number of peers in a single room"
+
+      - name: koalasync_memory_rss_bytes
+        path: '{.memory.rss}'
+        help: "Resident Set Size (RSS) memory usage in bytes"
+
+      - name: koalasync_memory_heap_used_bytes
+        path: '{.memory.heapUsed}'
+        help: "V8 engine heap used in bytes"
+
+      - name: koalasync_memory_heap_total_bytes
+        path: '{.memory.heapTotal}'
+        help: "V8 engine heap total in bytes"
+
+      # Rate limiter tracking — unique clients currently in each tracking window
+      # (not rate-limit denials; these include legitimate traffic too)
+
+      - name: koalasync_rate_limit_connections
+        path: '{.rateLimits.trackedClients.connections}'
+        help: "Unique clients tracked in the connection rate limiter window"
+
+      - name: koalasync_rate_limit_events
+        path: '{.rateLimits.trackedClients.events}'
+        help: "Unique sockets tracked in the event rate limiter window"
+
+      - name: koalasync_rate_limit_health
+        path: '{.rateLimits.trackedClients.health}'
+        help: "Unique IPs tracked in the health endpoint rate limiter window"
+
+      - name: koalasync_rate_limit_admin_metrics_auth
+        path: '{.rateLimits.trackedClients.adminMetricsAuth}'
+        help: "Unique IPs tracked in the admin metrics auth rate limiter window"
+
+      - name: koalasync_rate_limit_auth_failures
+        path: '{.rateLimits.trackedClients.authFailures}'
+        help: "Unique IPs tracked in the authentication failures cache"
+
+      - name: koalasync_rate_limit_room_list
+        path: '{.rateLimits.trackedClients.roomList}'
+        help: "Unique sockets in the room list cooldown cache"
+
+      # Actual rate-limit denials — incremented only when a 429 is served
+
+      - name: koalasync_rate_limit_denied_connections
+        path: '{.rateLimits.denied.connections}'
+        help: "Total connection attempts denied by rate limiter"
+
+      - name: koalasync_rate_limit_denied_events
+        path: '{.rateLimits.denied.events}'
+        help: "Total socket events denied by rate limiter"
+
+      - name: koalasync_rate_limit_denied_health
+        path: '{.rateLimits.denied.health}'
+        help: "Total health endpoint requests denied by rate limiter"
+
+      - name: koalasync_rate_limit_denied_admin_metrics_auth
+        path: '{.rateLimits.denied.adminMetricsAuth}'
+        help: "Total admin metrics auth attempts denied by rate limiter"
+
+      - name: koalasync_rate_limit_denied_room_list
+        path: '{.rateLimits.denied.roomList}'
+        help: "Total room list refresh requests denied by rate limiter"

extension/README.md

@@ -1,33 +1,106 @@
-# KoalaSync Chrome Extension
+# KoalaSync Browser Extension
 
-A Manifest V3 Chrome Extension for synchronized video playback across any website.
+This directory contains the Manifest V3 browser extension for Chrome and Firefox. It owns the popup UI, background service worker, content-script video control, invitation bridge, audio processing, and all browser-local settings.
+
+## Where You Are
+
+- `manifest.base.json` is the source manifest. The build script creates browser-specific `manifest.json` files in `dist/chrome/` and `dist/firefox/`.
+- `background.js` is the long-lived coordinator: WebSocket client, room state, host-control authority, heartbeat, reconnects, tab selection, and content-script injection.
+- `content.js` runs in the selected video tab. It detects video state, applies remote play/pause/seek, handles episode transitions, and applies local audio processing.
+- `popup.html` and `popup.js` implement the visible extension UI.
+- `extension/shared/` is generated by `npm run build:extension` from the root `shared/` directory. Do not edit it directly.
 
 ## Key Features
-- **Manifest V3**: Optimized Service Worker architecture with session persistence.
-- **Pure Vanilla JS**: No external dependencies or heavy libraries.
-- **Smart Peer IDs**: Hexadecimal IDs combined with customizable Usernames for easy identification.
-- **Dual Heartbeat**: Advanced session tracking (Background) and video synchronization (Content) to prevent ghost sessions.
-- **Live Diagnostics**: Built-in "Dev" tab for real-time video state debugging (ReadyState, CurrentTime, etc.).
+
+- **Manifest V3**: Service-worker architecture with session persistence and explicit keep-alive handling.
+- **Pure Vanilla JS**: No extension runtime dependencies and no bundler inside `extension/`.
+- **On-Demand Connection**: The service worker connects only while the user intends to be in a room.
+- **Host Control & Co-Hosts**: Hosts can switch a room into `host-only` mode and grant controller rights to trusted peers.
+- **Episode Auto-Sync**: Title/episode changes can open a lobby so peers resume together once everyone is ready.
+- **Smart Matching & Title Privacy**: Matching video tabs are highlighted, while tab/media title sharing can be reduced or disabled.
+- **Audio Processing**: Optional local compressor settings live in the dedicated audio options page.
+- **Status Diagnostics**: The Status tab exposes connection state, ping, video debug data, action history, and copyable logs.
+- **Dynamic i18n**: 15 languages are supported: `en`, `de`, `fr`, `es`, `it`, `nl`, `pl`, `pt`, `pt-BR`, `tr`, `ru`, `ja`, `ko`, `zh`, and `uk`.
 
 ## Tab Overview
-1. **Room**: Manage connections, view active peers, and share invitation links.
-2. **Sync**: Control video playback (Play/Pause/Force Sync) and view recent activity.
-3. **Settings**: Customize your Username and toggle domain-based Noise Filtering.
-4. **Dev**: Monitor connection status and view real-time video element metadata for debugging.
+
+1. **Room**: Select official/custom server, create or join rooms, view peers, share invite links, and manage Host Control when supported by the relay.
+2. **Sync**: Select the video tab, send play/pause/seek/force-sync actions, and view episode lobby state.
+3. **Settings**: Configure username, title sharing, noise filtering, auto episode sync, notifications, language, and audio options.
+4. **Status**: Inspect connection state, latency, video debug info, history, and logs for bug reports.
+5. **Dev**: Hidden developer-only controls shown for the `KoalaDev` username.
 
 ## Privacy & Permissions
-KoalaSync requires `<all_urls>` permission to detect and interact with video elements (`<video>`) on websites.
-- **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.
+
+KoalaSync requires `<all_urls>` host permission so it can detect and control `<video>` elements on arbitrary sites.
+
+- No browsing history is collected or uploaded.
+- Room credentials and user settings are stored locally with `chrome.storage`.
+- No analytics, external scripts, external fonts, or tracking libraries are used by the extension.
+- Audio processing is local to the selected tab.
+- Title privacy controls decide whether tab/media titles are shared with room peers.
 
 ## Installation
-1. **Sync Protocol**: Run `./scripts/sync-constants.sh` (macOS/Linux) or `scripts\sync-constants.bat` (Windows) from the root.
-2. Open Chrome and go to `chrome://extensions/`.
-3. Enable **Developer mode** (top right).
-4. Click **Load unpacked** and select the `extension` folder.
+
+From the repository root:
+```bash
+npm install
+npm run build:extension
+```
+
+Then load the generated bundle:
+
+- Chrome/Chromium: open `chrome://extensions/`, enable Developer Mode, and load `dist/chrome`.
+- Firefox: open `about:debugging`, choose **This Firefox**, and load `dist/firefox/manifest.json`.
 
 ## 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`
+
+Run the build whenever shared protocol files or extension packaging inputs change:
+```bash
+npm run build:extension
+```
+
+The build copies `shared/constants.js`, `shared/blacklist.js`, `shared/names.js`, and `shared/README.md` into `extension/shared/`, injects synchronous constants into `content.js`, generates browser manifests, and creates zip artifacts in `dist/`.
+
+Useful focused checks from the repository root:
+```bash
+node -c extension/background.js
+node -c extension/content.js
+node -c extension/popup.js
+node scripts/test-episode-utils.mjs
+node scripts/test-title-privacy.mjs
+node scripts/test-audio-settings.mjs
+node scripts/test-locales.cjs
+```
+
+For the full suite, run:
+```bash
+npm run verify
+```
+
+## Do Not Break
+
+- Keep `content.js` synchronous and IIFE-based; it cannot import ES modules directly.
+- Keep the injection markers used by `scripts/build-extension.cjs`.
+- Keep protocol names in `shared/constants.js` as the source of truth.
+- Keep extension runtime dependencies at zero unless the project explicitly decides to introduce a bundler.
+- Keep all extension assets self-hosted.
+
+## Module Structure
+
+| File | Purpose |
+|---|---|
+| `background.js` | Service worker: WebSocket protocol, room state, host control, tab/content routing, reconnects |
+| `content.js` | Video detection/control, audio processing, episode transition, host-only guest behavior |
+| `popup.js` | Popup UI: room join/create, tabs, settings, peer list, status, diagnostics |
+| `popup.html` | Popup markup, tabs, onboarding, status/debug surfaces |
+| `bridge.js` | Invitation bridge injected into `sync.koalastuff.net` |
+| `episode-utils.js` | Shared episode-title parser imported by background and injected into content at build time |
+| `title-privacy.js` | Tab/media title privacy modes and sanitization helpers |
+| `audio-options.html` / `audio-options.js` / `audio-options.css` | Dedicated local audio-processing settings page |
+| `page-api-seek-overrides.js` | Page-level seek bridge for site-specific player APIs |
+| `modules/tab-manager.js` | Tab lifecycle helper used by the background service worker |
+| `i18n.js` | Dynamic locale loader and DOM translation helper |
+| `locales/` | Runtime popup translations |
+| `_locales/` | Browser-store manifest translations |
+| `shared/` | Generated mirror of root shared constants, blacklist, names, and README |

extension/_locales/de/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Erstelle private Watch Partys und synchronisiere Videos mit Freunden auf YouTube, Netflix, Jellyfin, Emby und fast jeder Website."
+  }
+}

extension/_locales/en/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Create private watch parties and sync videos with friends on YouTube, Netflix, Jellyfin, Emby, and almost any HTML5 website."
+  }
+}

extension/_locales/es/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Crea fiestas privadas y sincroniza vídeos con amigos en YouTube, Netflix, Jellyfin, Emby y casi cualquier sitio HTML5."
+  }
+}

extension/_locales/fr/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Créez des watch parties privées et regardez en synchro entre amis sur YouTube, Netflix, Jellyfin, Emby et presque tout site HTML5."
+  }
+}

extension/_locales/it/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Crea watch party private e sincronizza i video con gli amici su YouTube, Netflix, Jellyfin, Emby e quasi ogni sito HTML5."
+  }
+}

extension/_locales/ja/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "プライベートなウォッチパーティーを作成し、YouTube、Netflix、Jellyfin、EmbyやほぼすべてのHTML5サイトで友達と動画を同期再生できます。"
+  }
+}

extension/_locales/ko/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "비공개 Watch Party를 만들고 YouTube, Netflix, Jellyfin, Emby 및 거의 모든 HTML5 사이트에서 친구들과 영상을 동기화하세요."
+  }
+}

extension/_locales/nl/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Maak privéwatchparty's en kijk synchroon met vrienden op YouTube, Netflix, Jellyfin, Emby en vrijwel elke HTML5-website."
+  }
+}

extension/_locales/pl/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Twórz prywatne wspólne seanse i synchronizuj filmy ze znajomymi na YouTube, Netflix, Jellyfin, Emby i niemal każdej stronie HTML5."
+  }
+}

extension/_locales/pt_BR/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Crie watch parties privadas e sincronize vídeos com amigos no YouTube, Netflix, Jellyfin, Emby e em quase qualquer site HTML5."
+  }
+}

extension/_locales/pt_PT/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Crie sessões privadas e veja vídeos sincronizados com amigos no YouTube, Netflix, Jellyfin, Emby e em quase qualquer site HTML5."
+  }
+}

extension/_locales/ru/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Создавайте закрытые Watch Party и смотрите синхронно с друзьями на YouTube, Netflix, Jellyfin, Emby и почти любом сайте HTML5."
+  }
+}

extension/_locales/tr/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Özel izleme partileri kurun; YouTube, Netflix, Jellyfin, Emby ve çoğu HTML5 sitesinde arkadaşlarınızla senkron izleyin."
+  }
+}

extension/_locales/uk/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "Створюйте закриті Watch Party й дивіться синхронно з друзями на YouTube, Netflix, Jellyfin, Emby та майже будь-якому сайті HTML5."
+  }
+}

extension/_locales/zh_CN/messages.json

@@ -0,0 +1,8 @@
+{
+  "appName": {
+    "message": "Watch Party - KoalaSync"
+  },
+  "appDesc": {
+    "message": "创建私人观影派对，与好友在 YouTube、Netflix、Jellyfin、Emby 及几乎任何 HTML5 视频网站同步观看。"
+  }
+}

extension/audio-options.css

@@ -0,0 +1,284 @@
+:root {
+    /* KoalaSync nature system: forest neutrals, eucalyptus brand, warm supporting accents. */
+    --bg-base: oklch(0.23 0.028 155);
+    --surface: oklch(0.30 0.035 150);
+    --surface-deep: oklch(0.205 0.025 155);
+    --surface-alt: oklch(0.265 0.032 150);
+    --border-soft: oklch(0.88 0.025 145 / 0.09);
+    --border-strong: oklch(0.39 0.038 145);
+    --text-primary: oklch(0.96 0.01 90);
+    --text-secondary: oklch(0.78 0.02 90);
+    --accent-green: oklch(0.73 0.13 155);
+    --accent-green-hover: oklch(0.79 0.12 155);
+    --accent-terracotta: oklch(0.62 0.14 45);
+    --success-green: oklch(0.72 0.14 135);
+    --warning-amber: oklch(0.76 0.14 80);
+    --danger: oklch(0.55 0.15 25);
+    --text-on-green: oklch(0.14 0.02 90);
+
+    --bg: var(--bg-base);
+    --card: var(--surface);
+    --panel: var(--surface-alt);
+    --accent: var(--accent-green);
+    --accent-hover: var(--accent-green-hover);
+    --text: var(--text-primary);
+    --text-muted: var(--text-secondary);
+    --border: var(--border-strong);
+    --radius: 8px;
+    color-scheme: dark;
+}
+
+html.theme-light {
+    --bg-base: oklch(0.965 0.012 105);
+    --surface: oklch(0.995 0.006 100);
+    --surface-deep: oklch(0.935 0.018 110);
+    --surface-alt: oklch(0.91 0.022 115);
+    --border-soft: oklch(0.28 0.035 140 / 0.10);
+    --border-strong: oklch(0.73 0.035 125);
+    --text-primary: oklch(0.21 0.03 140);
+    --text-secondary: oklch(0.43 0.03 135);
+    --accent-green: oklch(0.52 0.13 155);
+    --accent-green-hover: oklch(0.45 0.12 155);
+    --text-on-green: oklch(0.98 0.005 100);
+    color-scheme: light;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    min-height: 100vh;
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    font-size: 14px;
+}
+
+.page-shell {
+    width: min(760px, calc(100vw - 32px));
+    margin: 0 auto;
+    padding: 32px 0;
+}
+
+.page-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 20px;
+    margin-bottom: 18px;
+}
+
+.back-link {
+    display: inline-block;
+    color: var(--text-muted);
+    text-decoration: none;
+    font-size: 12px;
+    margin-bottom: 6px;
+    transition: color 0.2s;
+}
+.back-link:hover {
+    color: var(--accent);
+}
+
+.eyebrow {
+    margin: 0 0 4px;
+    color: var(--text-muted);
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    letter-spacing: 0.04em;
+}
+
+h1,
+h2,
+p {
+    margin: 0;
+}
+
+h1 {
+    color: var(--accent-hover);
+    font-size: 28px;
+    font-weight: 800;
+}
+
+h2 {
+    font-size: 16px;
+}
+
+.panel {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 20px;
+    margin-bottom: 16px;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+}
+
+html.theme-light .panel {
+    box-shadow: 0 12px 30px oklch(0.22 0.035 140 / 0.09);
+}
+
+.muted-panel {
+    color: var(--text-muted);
+}
+
+.section-heading,
+.master-toggle,
+.inline-toggle {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+}
+
+.master-toggle,
+.inline-toggle {
+    color: var(--text-muted);
+    font-size: 12px;
+    font-weight: 700;
+    letter-spacing: 0.01em;
+}
+
+.preset-group {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(148px, 1fr));
+    gap: 10px;
+    margin: 18px 0;
+}
+
+.preset-card {
+    min-height: 44px;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 10px 12px;
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    color: var(--text);
+    cursor: pointer;
+    transition: border-color 0.2s, box-shadow 0.2s;
+}
+.preset-card:hover {
+    border-color: color-mix(in oklch, var(--accent), transparent 60%);
+}
+
+.preset-card:has(input:checked) {
+    border-color: var(--accent);
+    box-shadow: 0 0 0 1px color-mix(in oklch, var(--accent), transparent 65%);
+}
+
+.preset-card input {
+    accent-color: var(--accent);
+}
+
+.custom-grid {
+    display: grid;
+    gap: 12px;
+    padding: 16px;
+    background: var(--surface-deep);
+    border: 1px solid var(--border-soft);
+    border-radius: var(--radius);
+    transition: opacity 0.3s;
+}
+
+.control-row {
+    display: grid;
+    grid-template-columns: 110px minmax(160px, 1fr) 78px 30px;
+    align-items: center;
+    gap: 10px;
+}
+
+.control-row label {
+    color: var(--text-muted);
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 0.01em;
+}
+
+input[type="range"] {
+    width: 100%;
+    accent-color: var(--accent);
+}
+
+input[type="number"] {
+    width: 100%;
+    padding: 8px;
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    color: var(--text);
+    font: inherit;
+    transition: border-color 0.2s;
+}
+input[type="number"]:focus {
+    border-color: var(--accent);
+    outline: none;
+}
+
+.unit {
+    color: var(--text-muted);
+    font-size: 12px;
+}
+
+.toggle-switch {
+    position: relative;
+    display: inline-block;
+    width: 38px;
+    height: 22px;
+    flex: 0 0 auto;
+}
+
+.toggle-switch input {
+    opacity: 0;
+    width: 0;
+    height: 0;
+}
+
+.slider {
+    position: absolute;
+    cursor: pointer;
+    inset: 0;
+    background-color: var(--border-strong);
+    transition: .3s;
+    border-radius: 22px;
+}
+
+.slider:before {
+    position: absolute;
+    content: "";
+    height: 16px;
+    width: 16px;
+    left: 3px;
+    bottom: 3px;
+    background-color: var(--text-secondary);
+    transition: .3s;
+    border-radius: 50%;
+}
+
+input:checked + .slider {
+    background-color: var(--accent);
+}
+
+input:checked + .slider:before {
+    transform: translateX(16px);
+    background-color: white;
+}
+
+@media (max-width: 620px) {
+    .page-header,
+    .section-heading {
+        align-items: flex-start;
+        flex-direction: column;
+    }
+
+    .control-row {
+        grid-template-columns: 1fr 74px 28px;
+    }
+
+    .control-row label {
+        grid-column: 1 / -1;
+    }
+}

extension/audio-options.html

@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>KoalaSync Audio Settings</title>
+    <script src="theme-init.js"></script>
+    <link rel="stylesheet" href="audio-options.css">
+</head>
+<body>
+    <main class="page-shell">
+        <header class="page-header">
+            <div>
+                <a id="backLink" href="#" class="back-link" data-i18n="AUDIO_BACK">← Back</a>
+                <p class="eyebrow">KoalaSync</p>
+                <h1 data-i18n="AUDIO_PAGE_TITLE">Audio Settings</h1>
+            </div>
+            <label class="master-toggle">
+                <span data-i18n="AUDIO_MASTER_TOGGLE">Audio Processing</span>
+                <span class="toggle-switch">
+                    <input type="checkbox" id="audioEnabled">
+                    <span class="slider"></span>
+                </span>
+            </label>
+        </header>
+
+        <section class="panel">
+            <div class="section-heading">
+                <h2 data-i18n="AUDIO_COMPRESSOR">Compressor</h2>
+                <label class="inline-toggle">
+                    <span data-i18n="AUDIO_COMPRESSOR_ENABLE">Enabled</span>
+                    <span class="toggle-switch">
+                        <input type="checkbox" id="compressorEnabled">
+                        <span class="slider"></span>
+                    </span>
+                </label>
+            </div>
+
+            <div class="preset-group" role="radiogroup" aria-label="Compressor preset">
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="recommended">
+                    <span data-i18n="AUDIO_PRESET_RECOMMENDED">Recommended</span>
+                </label>
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="dynamicRange">
+                    <span data-i18n="AUDIO_PRESET_DYNAMIC_RANGE">Dynamic Range</span>
+                </label>
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="vocalEnhancement">
+                    <span data-i18n="AUDIO_PRESET_VOCAL_ENHANCEMENT">Vocal Enhancement</span>
+                </label>
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="smooth">
+                    <span data-i18n="AUDIO_PRESET_SMOOTH">Smooth</span>
+                </label>
+                <label class="preset-card">
+                    <input type="radio" name="preset" value="custom">
+                    <span data-i18n="AUDIO_PRESET_CUSTOM">Custom</span>
+                </label>
+            </div>
+
+            <div class="custom-grid" id="customControls">
+                <div class="control-row" data-param="threshold">
+                    <label data-i18n="AUDIO_PARAM_THRESHOLD">Threshold</label>
+                    <input type="range" min="-60" max="0" step="1">
+                    <input type="number" min="-60" max="0" step="1">
+                    <span class="unit">dB</span>
+                </div>
+                <div class="control-row" data-param="knee">
+                    <label data-i18n="AUDIO_PARAM_KNEE">Knee</label>
+                    <input type="range" min="0" max="40" step="1">
+                    <input type="number" min="0" max="40" step="1">
+                    <span class="unit">dB</span>
+                </div>
+                <div class="control-row" data-param="ratio">
+                    <label data-i18n="AUDIO_PARAM_RATIO">Ratio</label>
+                    <input type="range" min="1" max="20" step="0.5">
+                    <input type="number" min="1" max="20" step="0.5">
+                    <span class="unit">:1</span>
+                </div>
+                <div class="control-row" data-param="attack">
+                    <label data-i18n="AUDIO_PARAM_ATTACK">Attack</label>
+                    <input type="range" min="0" max="1" step="0.001">
+                    <input type="number" min="0" max="1000" step="1" data-ms-input="true">
+                    <span class="unit">ms</span>
+                </div>
+                <div class="control-row" data-param="release">
+                    <label data-i18n="AUDIO_PARAM_RELEASE">Release</label>
+                    <input type="range" min="0" max="1" step="0.005">
+                    <input type="number" min="0" max="1000" step="5" data-ms-input="true">
+                    <span class="unit">ms</span>
+                </div>
+            </div>
+        </section>
+
+        <section class="panel muted-panel">
+            <div class="section-heading">
+                <h2 data-i18n="AUDIO_EQUALIZER">Equalizer</h2>
+            </div>
+            <p data-i18n="AUDIO_COMING_SOON">Coming soon</p>
+        </section>
+    </main>
+
+    <script src="audio-options.js" type="module"></script>
+</body>
+</html>

extension/audio-options.js

@@ -0,0 +1,192 @@
+import { loadLocale, translateDOM, getSystemLanguage } from './i18n.js';
+
+const PRESETS = {
+    recommended: { threshold: -24, ratio: 8, attack: 0.010, release: 0.300, knee: 15 },
+    dynamicRange: { threshold: -18, ratio: 4, attack: 0.020, release: 0.200, knee: 10 },
+    vocalEnhancement: { threshold: -12, ratio: 3, attack: 0.015, release: 0.150, knee: 5 },
+    smooth: { threshold: -30, ratio: 1.5, attack: 0.030, release: 0.250, knee: 20 },
+    custom: { threshold: -24, ratio: 12, attack: 0.003, release: 0.250, knee: 30 }
+};
+
+const DEFAULT_AUDIO_SETTINGS = {
+    enabled: false,
+    compressor: {
+        enabled: false,
+        preset: 'recommended',
+        customParams: { ...PRESETS.custom }
+    }
+};
+const PARAM_LIMITS = {
+    threshold: { min: -60, max: 0 },
+    knee: { min: 0, max: 40 },
+    ratio: { min: 1, max: 20 },
+    attack: { min: 0, max: 1 },
+    release: { min: 0, max: 1 }
+};
+
+const elements = {
+    audioEnabled: document.getElementById('audioEnabled'),
+    compressorEnabled: document.getElementById('compressorEnabled'),
+    presetInputs: Array.from(document.querySelectorAll('input[name="preset"]')),
+    controlRows: Array.from(document.querySelectorAll('.control-row')),
+    backLink: document.getElementById('backLink')
+};
+
+let saveTimer = null;
+let isRendering = false;
+
+function cloneDefaultSettings() {
+    return JSON.parse(JSON.stringify(DEFAULT_AUDIO_SETTINGS));
+}
+
+let currentSettings = cloneDefaultSettings();
+
+function mergeAudioSettings(settings = {}) {
+    const safeSettings = settings && typeof settings === 'object' ? settings : {};
+    const defaults = cloneDefaultSettings();
+    return {
+        ...defaults,
+        ...safeSettings,
+        compressor: {
+            ...defaults.compressor,
+            ...(safeSettings.compressor || {}),
+            customParams: {
+                ...defaults.compressor.customParams,
+                ...(safeSettings.compressor?.customParams || {})
+            }
+        }
+    };
+}
+
+function debounceSave() {
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+        chrome.storage.local.set({ audioSettings: currentSettings });
+    }, 40);
+}
+
+function getParamValue(param, value, isMsInput = false) {
+    const parsed = Number(value);
+    const candidate = Number.isFinite(parsed)
+        ? (isMsInput ? parsed / 1000 : parsed)
+        : currentSettings.compressor.customParams[param];
+    const limits = PARAM_LIMITS[param];
+    if (!limits) return candidate;
+    return Math.min(limits.max, Math.max(limits.min, candidate));
+}
+
+function formatNumber(value, param, isMsInput = false) {
+    if (isMsInput) return Math.round(value * 1000);
+    if (param === 'ratio') return Number(value).toFixed(1).replace(/\.0$/, '');
+    return value;
+}
+
+function render() {
+    isRendering = true;
+    elements.audioEnabled.checked = currentSettings.enabled === true;
+    elements.compressorEnabled.checked = currentSettings.compressor.enabled === true;
+
+    const selectedPreset = currentSettings.compressor.preset || 'recommended';
+    elements.presetInputs.forEach(input => {
+        input.checked = input.value === selectedPreset;
+    });
+
+    const params = selectedPreset === 'custom'
+        ? currentSettings.compressor.customParams
+        : PRESETS[selectedPreset] || PRESETS.recommended;
+
+    elements.controlRows.forEach(row => {
+        const param = row.dataset.param;
+        const range = row.querySelector('input[type="range"]');
+        const number = row.querySelector('input[type="number"]');
+        const value = params[param];
+        range.value = value;
+        number.value = formatNumber(value, param, number.dataset.msInput === 'true');
+    });
+    isRendering = false;
+}
+
+function setPreset(preset) {
+    currentSettings.compressor.preset = preset;
+    if (preset === 'custom') {
+        currentSettings.compressor.customParams = {
+            ...PRESETS.custom,
+            ...currentSettings.compressor.customParams
+        };
+    }
+    render();
+    debounceSave();
+}
+
+function setCustomParam(param, value) {
+    currentSettings.compressor.preset = 'custom';
+    currentSettings.compressor.customParams[param] = getParamValue(param, value);
+    render();
+    debounceSave();
+}
+
+async function init() {
+    // Local-only: audioSettings/locale are never read from storage.sync.
+    const { audioSettings, locale } = await chrome.storage.local.get(['audioSettings', 'locale']);
+    const lang = locale || getSystemLanguage();
+    await loadLocale(lang);
+    translateDOM();
+
+    currentSettings = mergeAudioSettings(audioSettings);
+    render();
+}
+
+elements.audioEnabled.addEventListener('change', () => {
+    currentSettings.enabled = elements.audioEnabled.checked;
+    if (currentSettings.enabled && !currentSettings.compressor.enabled) {
+        currentSettings.compressor.enabled = true;
+    }
+    render();
+    debounceSave();
+});
+
+elements.compressorEnabled.addEventListener('change', () => {
+    currentSettings.compressor.enabled = elements.compressorEnabled.checked;
+    if (currentSettings.compressor.enabled) currentSettings.enabled = true;
+    render();
+    debounceSave();
+});
+
+elements.presetInputs.forEach(input => {
+    input.addEventListener('change', () => {
+        if (input.checked) setPreset(input.value);
+    });
+});
+
+elements.controlRows.forEach(row => {
+    const param = row.dataset.param;
+    const range = row.querySelector('input[type="range"]');
+    const number = row.querySelector('input[type="number"]');
+
+    range.addEventListener('input', () => {
+        if (isRendering) return;
+        setCustomParam(param, getParamValue(param, range.value));
+    });
+
+    number.addEventListener('input', () => {
+        if (isRendering) return;
+        setCustomParam(param, getParamValue(param, number.value, number.dataset.msInput === 'true'));
+    });
+});
+
+chrome.storage.onChanged.addListener((changes, area) => {
+    if (area !== 'local' || !changes.audioSettings) return;
+    currentSettings = mergeAudioSettings(changes.audioSettings.newValue);
+    render();
+});
+
+if (elements.backLink) {
+    elements.backLink.addEventListener('click', (e) => {
+        e.preventDefault();
+        window.close();
+    });
+}
+
+init().catch(err => {
+    console.error('[AudioOptions] Failed to initialize:', err);
+});

extension/bridge.js

@@ -1,6 +1,7 @@
+/* global cloneInto */
 /**
  * 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.
  */
 
@@ -9,6 +10,7 @@ document.documentElement.dataset.koalasyncInstalled = 'true';
 
 // 2. Listen for Join Requests from the Website
 window.addEventListener('KOALASYNC_JOIN_REQUEST', (e) => {
+    if (!e || !e.detail) return;
     const { roomId, password, useCustomServer, serverUrl } = e.detail;
     chrome.runtime.sendMessage({ 
         type: 'WEB_JOIN_REQUEST', 
@@ -16,18 +18,22 @@ window.addEventListener('KOALASYNC_JOIN_REQUEST', (e) => {
         password,
         useCustomServer,
         serverUrl
-    });
+    }).catch(() => {});
 });
 
 // 3. Listen for Status Updates from the Extension and relay to Website
 chrome.runtime.onMessage.addListener((msg) => {
+    if (!msg) return;
     if (msg.type === 'JOIN_STATUS') {
-        const event = new CustomEvent('KOALASYNC_STATUS', { 
-            detail: { 
-                success: msg.success, 
-                message: msg.message 
-            } 
-        });
-        window.dispatchEvent(event);
+        const detail = { success: msg.success, message: msg.message };
+        // Firefox MV3 content scripts run in an isolated world. When dispatching
+        // a CustomEvent with a detail object, Firefox wraps it in an XrayWrapper
+        // that the page's JavaScript cannot destructure (Permission denied).
+        // cloneInto() exposes the object to the page's context correctly.
+        // Chrome doesn't have this issue — cloneInto() is undefined there.
+        const safeDetail = typeof cloneInto === 'function'
+            ? cloneInto(detail, document.defaultView)
+            : detail;
+        window.dispatchEvent(new CustomEvent('KOALASYNC_STATUS', { detail: safeDetail }));
     }
 });

extension/episode-utils.js

@@ -0,0 +1,24 @@
+/**
+ * KoalaSync Episode Title Utilities
+ * Single source of truth — synced to content.js by build-extension.cjs.
+ * Keep in sync with the injection block in content.js!
+ */
+
+export function extractEpisodeId(title) {
+    if (!title || typeof title !== 'string') return null;
+    const se = title.match(/S(?:eason\s*)?(\d+)[^a-zA-Z0-9]*E(?:pisode\s*)?(\d+)/i);
+    if (se) return `S${String(se[1]).padStart(2, '0')}E${String(se[2]).padStart(2, '0')}`;
+    const ep = title.match(/(?:Episode|Folge|Ep\.?|#)\s*(\d+)/i);
+    if (ep) return `EP${String(ep[1]).padStart(3, '0')}`;
+    return null;
+}
+
+export function sameEpisode(titleA, titleB) {
+    if (!titleA && !titleB) return true;
+    if (!titleA || !titleB) return false;
+    const idA = extractEpisodeId(titleA);
+    const idB = extractEpisodeId(titleB);
+    if (idA && idB) return idA === idB;
+    if (idA || idB) return false;
+    return titleA === titleB;
+}

extension/host-access.js

@@ -0,0 +1,194 @@
+export const HOST_ACCESS_REQUIRED_STATUS = 'host_permission_required';
+
+export function normalizeTabId(value) {
+    if (typeof value === 'number') {
+        return Number.isSafeInteger(value) && value > 0 ? value : null;
+    }
+    if (typeof value !== 'string') return null;
+
+    const normalized = value.trim();
+    if (!/^[1-9]\d*$/.test(normalized)) return null;
+    const tabId = Number(normalized);
+    return Number.isSafeInteger(tabId) ? tabId : null;
+}
+
+function browserSupportsPortMatchPatterns(chromeApi) {
+    // runtime.getBrowserInfo is a Firefox-only WebExtension API. Firefox does
+    // not accept ports in match patterns, while Chromium does.
+    return typeof chromeApi?.runtime?.getBrowserInfo !== 'function';
+}
+
+export function describeTabUrl(rawUrl, { includePort = true } = {}) {
+    if (typeof rawUrl !== 'string' || !rawUrl) return null;
+
+    try {
+        const url = new URL(rawUrl);
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            const permissionHost = includePort ? url.host : url.hostname;
+            return {
+                url: rawUrl,
+                host: url.host,
+                originPattern: `${url.protocol}//${permissionHost}/*`
+            };
+        }
+        if (url.protocol === 'file:') {
+            return {
+                url: rawUrl,
+                host: 'local file',
+                originPattern: 'file:///*'
+            };
+        }
+    } catch (_e) {
+        // Invalid and browser-internal URLs cannot receive host access.
+    }
+
+    return null;
+}
+
+export async function inspectTabHostAccess(chromeApi, tabId) {
+    const tab = await chromeApi.tabs.get(tabId);
+    // executeScript targets the committed document. pendingUrl may already point
+    // at another origin while tab.url is still the document being injected into.
+    const descriptor = describeTabUrl(tab?.url || tab?.pendingUrl || '', {
+        includePort: browserSupportsPortMatchPatterns(chromeApi)
+    });
+    if (!descriptor) {
+        return {
+            tab,
+            url: tab?.url || '',
+            host: null,
+            originPattern: null,
+            granted: null
+        };
+    }
+
+    if (typeof chromeApi.permissions?.contains !== 'function') {
+        return { tab, ...descriptor, granted: null };
+    }
+
+    try {
+        const granted = await callBooleanPermissionMethod(
+            chromeApi,
+            'contains',
+            { origins: [descriptor.originPattern] },
+            { timeoutMs: 1000 }
+        );
+        return {
+            tab,
+            ...descriptor,
+            granted: granted === null ? null : granted === true
+        };
+    } catch (_e) {
+        // Permission inspection is advisory. The actual script injection below
+        // remains the source of truth, including temporary activeTab access.
+        return { tab, ...descriptor, granted: null };
+    }
+}
+
+function callBooleanPermissionMethod(chromeApi, methodName, request, { timeoutMs = null } = {}) {
+    const method = chromeApi.permissions?.[methodName];
+    if (typeof method !== 'function') return Promise.resolve(null);
+
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timeout = null;
+        const clearSettlementTimeout = () => {
+            if (timeout !== null) {
+                clearTimeout(timeout);
+                timeout = null;
+            }
+        };
+        const finish = (value) => {
+            if (settled) return;
+            settled = true;
+            clearSettlementTimeout();
+            resolve(value === true ? true : value === false ? false : null);
+        };
+        const fail = (error) => {
+            if (settled) return;
+            settled = true;
+            clearSettlementTimeout();
+            reject(error instanceof Error ? error : new Error(String(error || 'Permission request failed')));
+        };
+        const callback = (value) => {
+            const lastError = chromeApi.runtime?.lastError;
+            if (lastError) {
+                fail(new Error(lastError.message || String(lastError)));
+                return;
+            }
+            finish(value);
+        };
+
+        if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+            timeout = setTimeout(() => finish(null), timeoutMs);
+        }
+
+        try {
+            const result = method.call(chromeApi.permissions, request, callback);
+            if (result && typeof result.then === 'function') {
+                result.then(finish, fail);
+            } else if (typeof result === 'boolean') {
+                finish(result);
+            }
+            // Callback-based Chromium/Firefox APIs return undefined and settle
+            // through callback. Promise-based implementations settle above.
+        } catch (error) {
+            fail(error);
+        }
+    });
+}
+
+export function requestOriginPermission(chromeApi, originPattern) {
+    if (typeof originPattern !== 'string' || !originPattern) {
+        return Promise.resolve(null);
+    }
+    return callBooleanPermissionMethod(
+        chromeApi,
+        'request',
+        { origins: [originPattern] },
+        { timeoutMs: 60000 }
+    ).catch(() => false);
+}
+
+export function isHostAccessError(error) {
+    const message = typeof error?.message === 'string' ? error.message : String(error || '');
+    return /host permission|permission to access (?:this|the|respective) host|cannot access contents of/i.test(message);
+}
+
+function hostAccessRequestDetails(tabId, originPattern) {
+    const request = { tabId };
+    if (typeof originPattern === 'string' && originPattern) {
+        request.pattern = originPattern;
+    }
+    return request;
+}
+
+export async function addTabHostAccessRequest(chromeApi, tabId, originPattern = null) {
+    if (typeof chromeApi.permissions?.addHostAccessRequest !== 'function') {
+        return false;
+    }
+
+    try {
+        await chromeApi.permissions.addHostAccessRequest(
+            hostAccessRequestDetails(tabId, originPattern)
+        );
+        return true;
+    } catch (_e) {
+        return false;
+    }
+}
+
+export async function removeTabHostAccessRequest(chromeApi, tabId, originPattern = null) {
+    if (typeof chromeApi.permissions?.removeHostAccessRequest !== 'function') {
+        return false;
+    }
+
+    try {
+        await chromeApi.permissions.removeHostAccessRequest(
+            hostAccessRequestDetails(tabId, originPattern)
+        );
+        return true;
+    } catch (_e) {
+        return false;
+    }
+}

extension/i18n.js

@@ -0,0 +1,141 @@
+// extension/i18n.js
+export const SUPPORTED_LANGUAGES = ['en', 'de', 'fr', 'es', 'it', 'nl', 'pl', 'pt', 'pt-BR', 'tr', 'ru', 'ja', 'ko', 'zh', 'uk'];
+export const DEFAULT_LANGUAGE = 'en';
+
+let activeDictionary = {};
+const dictionaryCache = {};
+let currentLanguage = null;
+
+/**
+ * Resolves, loads, and merges the target language with the English baseline fallback.
+ * @param {string} langCode - Target language (e.g. 'de')
+ */
+export async function loadLocale(langCode) {
+    const resolvedLang = SUPPORTED_LANGUAGES.includes(langCode) ? langCode : DEFAULT_LANGUAGE;
+    if (typeof document !== 'undefined') {
+        document.documentElement.lang = resolvedLang;
+    }
+    
+    if (currentLanguage === resolvedLang && Object.keys(activeDictionary).length > 0) {
+        return;
+    }
+
+    if (dictionaryCache[resolvedLang]) {
+        activeDictionary = dictionaryCache[resolvedLang];
+        currentLanguage = resolvedLang;
+        return;
+    }
+    
+    try {
+        // Load Baseline English
+        let enDict;
+        if (dictionaryCache[DEFAULT_LANGUAGE]) {
+            enDict = dictionaryCache[DEFAULT_LANGUAGE];
+        } else {
+            const enResponse = await fetch(chrome.runtime.getURL(`locales/${DEFAULT_LANGUAGE}.json`));
+            enDict = await enResponse.json();
+            dictionaryCache[DEFAULT_LANGUAGE] = enDict;
+        }
+        
+        if (resolvedLang === DEFAULT_LANGUAGE) {
+            activeDictionary = enDict;
+            currentLanguage = resolvedLang;
+            return;
+        }
+        
+        // Load Target Locale
+        const targetResponse = await fetch(chrome.runtime.getURL(`locales/${resolvedLang}.json`));
+        const targetDict = await targetResponse.json();
+        
+        // Airtight Fallback Merge: target overrides en, missing elements fallback to en
+        const mergedDict = Object.assign({}, enDict, targetDict);
+        dictionaryCache[resolvedLang] = mergedDict;
+        activeDictionary = mergedDict;
+        currentLanguage = resolvedLang;
+    } catch (err) {
+        console.error('[i18n] Failed to load locale. Defaulting to English:', err);
+        // Fallback directly to static English if fetching fails
+        try {
+            let enDict;
+            if (dictionaryCache[DEFAULT_LANGUAGE]) {
+                enDict = dictionaryCache[DEFAULT_LANGUAGE];
+            } else {
+                const enResponse = await fetch(chrome.runtime.getURL(`locales/${DEFAULT_LANGUAGE}.json`));
+                enDict = await enResponse.json();
+                dictionaryCache[DEFAULT_LANGUAGE] = enDict;
+            }
+            activeDictionary = enDict;
+            currentLanguage = DEFAULT_LANGUAGE;
+        } catch (_) {
+            activeDictionary = {};
+            currentLanguage = null;
+        }
+    }
+}
+
+/**
+ * Returns the translated string for a given key. Supports optional value interpolation.
+ * @param {string} key - Dictionary key
+ * @param {object} [placeholders] - Key-value map for replacements (e.g., { name: 'Alice' })
+ * @returns {string} Translated string or the key itself
+ */
+export function getMessage(key, placeholders = null) {
+    let msg = activeDictionary[key] !== undefined ? String(activeDictionary[key]) : key;
+    if (placeholders && typeof placeholders === 'object') {
+        for (const [k, v] of Object.entries(placeholders)) {
+            msg = msg.replace(new RegExp(`{${k}}`, 'g'), v);
+        }
+    }
+    return msg;
+}
+
+/**
+ * Performs dynamic DOM replacements for elements carrying data-i18n attributes.
+ */
+export function translateDOM() {
+    if (typeof document === 'undefined') return;
+
+    // 1. Text Content
+    document.querySelectorAll('[data-i18n]').forEach(el => {
+        const key = el.getAttribute('data-i18n');
+        const translated = getMessage(key);
+        
+        // Special case: Preserve logo image elements inside headers (like h1 logo)
+        const img = el.querySelector('img');
+        if (img) {
+            el.innerHTML = '';
+            el.appendChild(img);
+            el.appendChild(document.createTextNode(' ' + translated));
+        } else {
+            el.textContent = translated;
+        }
+    });
+
+    // 2. Tooltips (titles)
+    document.querySelectorAll('[data-i18n-title]').forEach(el => {
+        const key = el.getAttribute('data-i18n-title');
+        el.setAttribute('title', getMessage(key));
+    });
+
+    // 3. Placeholders
+    document.querySelectorAll('[data-i18n-placeholder]').forEach(el => {
+        const key = el.getAttribute('data-i18n-placeholder');
+        el.setAttribute('placeholder', getMessage(key));
+    });
+}
+
+/**
+ * Detects and maps the user's system language to the best supported locale.
+ * @returns {string} Supported language code
+ */
+export function getSystemLanguage() {
+    const uiLang = (typeof chrome !== 'undefined' && chrome.i18n && chrome.i18n.getUILanguage) 
+        ? chrome.i18n.getUILanguage() 
+        : '';
+    const fullLang = (navigator.language || uiLang || '').toLowerCase();
+    if (fullLang.startsWith('pt-br')) {
+        return 'pt-BR';
+    }
+    const baseLang = fullLang.split('-')[0];
+    return SUPPORTED_LANGUAGES.includes(baseLang) ? baseLang : DEFAULT_LANGUAGE;
+}

extension/icons/pause.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
+  <path d="M3 2.5h4v11H3zm6 0h4v11H9z"/>
+</svg>

extension/icons/play.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
+  <path d="M4 2.6v10.8L13 8z"/>
+</svg>

extension/icons/sync.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
+  <path d="M13.4 5.5A5.8 5.8 0 0 0 3 4.2L1.7 2.9v4.4h4.4L4.4 5.6a4 4 0 0 1 7.2.8zM2.6 10.5A5.8 5.8 0 0 0 13 11.8l1.3 1.3V8.7H9.9l1.7 1.7a4 4 0 0 1-7.2-.8z"/>
+</svg>

extension/locales/de.json

@@ -0,0 +1,249 @@
+{
+  "LANG_CODE": "de",
+  "HTML_CLASS": "lang-de",
+  "APP_TITLE": "KoalaSync",
+  "TAB_ROOM": "Raum",
+  "TAB_ROOM_TOOLTIP": "Raum-Einstellungen und Verbindung",
+  "TAB_SYNC": "Sync",
+  "TAB_SYNC_TOOLTIP": "Video-Synchronisations-Steuerung und Aktionen",
+  "TAB_SETTINGS": "Optionen",
+  "TAB_SETTINGS_TOOLTIP": "Erweiterungseinstellungen",
+  "TAB_STATUS": "Status",
+  "TAB_STATUS_TOOLTIP": "Erweiterte Diagnose & Protokolle",
+  "BTN_CREATE_ROOM": "+ Neuer Raum",
+  "MANUAL_CONNECT_HEADER": "Manuell verbinden / Erweitert",
+  "LABEL_SERVER": "Server",
+  "BTN_SERVER_OFFICIAL": "Offiziell",
+  "BTN_SERVER_OFFICIAL_TOOLTIP": "Verwende den offiziellen, zuverlässigen Server",
+  "BTN_SERVER_CUSTOM": "Eigener",
+  "BTN_SERVER_CUSTOM_TOOLTIP": "Verbinde dich mit deinem eigenen, selbstgehosteten Server",
+  "PLACEHOLDER_SERVER_URL": "wss://dein-server:3000",
+  "LABEL_ROOM_ID": "Raum-ID",
+  "LABEL_ROOM_ID_TOOLTIP": "Der eindeutige Identifikator für deinen Sync-Raum",
+  "PLACEHOLDER_ROOM_ID": "Raum-ID eingeben",
+  "PLACEHOLDER_ROOM_ID_TOOLTIP": "Die eindeutige ID des Raums, dem du beitreten möchtest",
+  "LABEL_PASSWORD": "Passwort (Optional)",
+  "LABEL_PASSWORD_TOOLTIP": "Optionales Passwort, um den Raumzugang zu beschränken",
+  "PLACEHOLDER_PASSWORD": "Raum-Passwort (optional)",
+  "PLACEHOLDER_PASSWORD_TOOLTIP": "Passwort für den Raum (leer lassen, wenn keines vorhanden)",
+  "BTN_JOIN_ROOM": "Raum beitreten / erstellen",
+  "BTN_JOIN_ROOM_TOOLTIP": "Mit dem Raum verbinden",
+  "LABEL_PUBLIC_ROOMS": "Öffentliche Räume",
+  "LABEL_PUBLIC_ROOMS_TOOLTIP": "Liste der öffentlich verfügbaren Räume auf diesem Server",
+  "BTN_REFRESH": "AKTUALISIEREN",
+  "BTN_REFRESH_TOOLTIP": "Die Liste der öffentlichen Räume aktualisieren",
+  "PUBLIC_ROOMS_REFRESHING": "Aktualisiere...",
+  "BTN_REFRESH_COOLDOWN": "WARTE {seconds}s",
+  "BTN_REFRESH_COOLDOWN_TOOLTIP": "Die Raumliste kühlt ab. Versuche es in {seconds}s erneut.",
+  "PUBLIC_ROOMS_REFRESHING_COOLDOWN": "Aktualisiere öffentliche Räume. Nächste Aktualisierung in {seconds}s verfügbar.",
+  "LABEL_ACTIVE_ROOM": "Aktiver Raum",
+  "LABEL_ACTIVE_ROOM_TOOLTIP": "Der Raum, mit dem du gerade verbunden bist",
+  "ACTIVE_ROOM_NONE": "KEINER",
+  "ACTIVE_SERVER_OFFICIAL": "Offizieller Server",
+  "LABEL_INVITE_LINK": "Einladungslink",
+  "LABEL_INVITE_LINK_TOOLTIP": "Teile diesen Link mit Freunden, damit sie beitreten können",
+  "LABEL_PEERS_IN_ROOM": "Teilnehmer im Raum",
+  "LABEL_PEERS_IN_ROOM_TOOLTIP": "Andere Benutzer, die derzeit mit diesem Raum verbunden sind",
+  "LABEL_HOST_CONTROL": "Host-Steuerung",
+  "LABEL_HOST_CONTROL_TOOLTIP": "Festlegen, wer die Wiedergabe in diesem Raum steuern darf",
+  "LABEL_HOST_ONLY_TOGGLE": "Nur ich darf die Wiedergabe steuern",
+  "NOTICE_HOST_CONTROLS": "Der Host steuert die Wiedergabe für alle.",
+  "NOTICE_COHOST_HINT": "Tipp: Gib einzelnen Teilnehmern unten in der Teilnehmerliste die Steuerung.",
+  "BADGE_HOST": "Host",
+  "BADGE_GUEST": "Gast",
+  "BADGE_CONTROLLER": "Controller",
+  "BTN_GIVE_CONTROL": "Steuerung geben",
+  "BTN_REVOKE_CONTROL": "Entziehen",
+  "BADGE_DESYNCED": "Solo",
+  "TOOLTIP_PEER_DESYNCED": "Schaut alleine — ignoriert die Befehle des Hosts",
+  "HCM_DIALOG_TITLE": "KoalaSync · Der Host steuert diesen Raum",
+  "HCM_DIALOG_BODY": "Nur der Host kann die Wiedergabe in diesem Raum steuern. Weiter gemeinsam schauen oder allein weiterschauen?",
+  "HCM_DIALOG_STAY": "Synchron bleiben",
+  "HCM_DIALOG_SOLO": "Allein weiterschauen",
+  "HCM_BADGE_SOLO": "Du schaust allein",
+  "HCM_BADGE_RESYNC": "Neu sync",
+  "NO_PEERS_CONNECTED": "Keine Teilnehmer verbunden",
+  "BTN_LEAVE_ROOM": "Raum verlassen",
+  "LABEL_SELECT_VIDEO": "Video auswählen",
+  "LABEL_SELECT_VIDEO_TOOLTIP": "Wähle den Browser-Tab aus, der das zu synchronisierende Video enthält",
+  "OPTION_SELECT_TAB": "-- Wähle einen Tab --",
+  "LABEL_REMOTE_CONTROL": "Fernsteuerung",
+  "BTN_COPY_INVITE": "📋 Einladungslink",
+  "BTN_COPY_INVITE_TOOLTIP": "Einladungslink kopieren",
+  "BTN_PLAY": "Abspielen",
+  "BTN_PLAY_TOOLTIP": "Sende einen Play-Befehl an alle",
+  "BTN_PAUSE": "Pause",
+  "BTN_PAUSE_TOOLTIP": "Sende einen Pause-Befehl an alle",
+  "BTN_SYNC": "Sync",
+  "BTN_SYNC_TOOLTIP": "Erzwinge die Synchronisation aller Teilnehmer",
+  "OPTION_JUMP_TO_OTHERS": "Zu anderen springen",
+  "OPTION_JUMP_TO_ME": "Zu mir springen",
+  "OPTION_JUMP_MODE_TOOLTIP": "Synchronisationsziel auswählen",
+  "LABEL_LAST_ACTIVITY": "Letzter Aktivitätsstatus",
+  "LABEL_LAST_ACTIVITY_TOOLTIP": "Zeigt den neuesten Play-, Pause- oder Seek-Befehl",
+  "NO_RECENT_COMMANDS": "Keine aktuellen Befehle",
+  "LOBBY_HEADER": "EPISODEN-LOBBY",
+  "LOBBY_WAITING_FOR": "🎬 Warte auf: \"{title}\"",
+  "LOBBY_WAITING_PEERS": "Warte auf Teilnehmer...",
+  "BTN_SKIP_PLAY": "Überspringen & Abspielen",
+  "BTN_SKIP_PLAY_TOOLTIP": "Lobby abbrechen und trotzdem abspielen",
+  "LOBBY_CONNECT_FIRST": "Zuerst Raum beitreten",
+  "LOBBY_CONNECT_FIRST_DESC": "Du musst über einen Einladungslink beitreten oder einen neuen Raum erstellen, um Videos zu synchronisieren.",
+  "BTN_CREATE_ROOM_ALT": "Neuen Raum erstellen",
+  "BTN_CREATE_ROOM_ALT_TOOLTIP": "Einen neuen zufälligen Raum erstellen und beitreten",
+  "LABEL_USERNAME": "Dein Benutzername",
+  "LABEL_USERNAME_TOOLTIP": "Der Benutzername hilft anderen, dich zu identifizieren.",
+  "PLACEHOLDER_USERNAME": "Anonymer Koala",
+  "LABEL_HIDE_CLUTTER": "Aufgeräumte Tab-Liste",
+  "LABEL_HIDE_CLUTTER_TOOLTIP": "Filtert Nicht-Video-Tabs und irrelevante Domains heraus, um die Liste sauber zu halten",
+  "LABEL_AUTO_SYNC_NEXT": "Nächste Episode auto-syncen",
+  "LABEL_AUTO_SYNC_NEXT_TOOLTIP": "Pausiert automatisch und wartet auf alle Teilnehmer bei Episodenwechsel, startet dann synchron.",
+  "LABEL_AUTO_COPY_INVITE": "Einladungslink auto-kopieren",
+  "LABEL_AUTO_COPY_INVITE_TOOLTIP": "Kopiert den Einladungslink automatisch beim Erstellen eines Raums.",
+  "LABEL_NOTIFICATIONS": "Browser-Benachrichtigungen",
+  "LABEL_NOTIFICATIONS_TOOLTIP": "Zeigt Systembenachrichtigungen, wenn jemand beitritt/verlässt oder abspielt/pausiert.",
+  "LABEL_LANGUAGE": "Sprache",
+  "LABEL_LANGUAGE_TOOLTIP": "Wähle deine bevorzugte Sprache für die Erweiterung aus",
+  "LABEL_TROUBLESHOOTING": "Fehlerbehebung",
+  "LABEL_TROUBLESHOOTING_TOOLTIP": "Werkzeuge zur Behebung von Verbindungsproblemen",
+  "BTN_REGEN_ID": "Peer-ID neu generieren",
+  "BTN_REGEN_ID_TOOLTIP": "Generiere deine interne ID neu und verbinde dich erneut",
+  "REGEN_ID_DESC": "Verwende dies, wenn du Fehler wegen doppelter Identität siehst.",
+  "REGEN_ID_OTHER_ISSUE": "Anderes Problem? Öffne ein GitHub Issue",
+  "TOAST_ID_REGENERATED": "Identität neu generiert — Verbindung wird wiederhergestellt…",
+  "LABEL_CONN_STATUS": "Verbindungsstatus",
+  "LABEL_CONN_STATUS_TOOLTIP": "Aktueller WebSocket-Verbindungsstatus",
+  "CONN_STATUS_DISCONNECTED": "Getrennt",
+  "BTN_RETRY": "WIEDERHOLEN",
+  "BTN_RETRY_TOOLTIP": "Versuchen, die Verbindung zum Server wiederherzustellen",
+  "BTN_COPY_LOGS": "Logs kopieren",
+  "BTN_COPY_LOGS_TOOLTIP": "Logs zum Teilen in die Zwischenablage kopieren",
+  "LABEL_VIDEO_DEBUG": "Video-Debug-Info",
+  "LABEL_VIDEO_DEBUG_TOOLTIP": "Technische Details zum aktuell ausgewählten Video-Element",
+  "VIDEO_DEBUG_EMPTY": "Kein Tab ausgewählt oder kein Video erkannt.",
+  "LABEL_HISTORY": "Aktionsverlauf",
+  "LABEL_HISTORY_TOOLTIP": "Chronologisches Protokoll aller Sync-Befehle im Raum",
+  "HISTORY_EMPTY": "Noch keine Aktivität",
+  "LABEL_LOGS": "Logs (Letzte 50)",
+  "LABEL_LOGS_TOOLTIP": "Technische Verbindungsprotokolle zur Fehlersuche",
+  "BTN_CLEAR": "LEEREN",
+  "BTN_CLEAR_TOOLTIP": "Protokollausgabe leeren",
+  "LABEL_GITHUB": "GitHub-Repository",
+  "BTN_ONBOARDING_SKIP": "Überspringen",
+  "BTN_ONBOARDING_SKIP_TOOLTIP": "Einführung überspringen",
+  "BTN_ONBOARDING_NEXT": "Weiter",
+  "BTN_ONBOARDING_NEXT_TOOLTIP": "Zum nächsten Schritt gehen",
+  "ONBOARDING_1_TITLE": "Willkommen bei KoalaSync!",
+  "ONBOARDING_1_TEXT": "Schau Videos in perfekter Synchronität zusammen — egal wo ihr seid. Machen wir eine kurze Tour!",
+  "ONBOARDING_2_TITLE": "1. Raum erstellen",
+  "ONBOARDING_2_TEXT": "Hier geht's los. Erstelle einen Raum und teile den Einladungslink mit deinen Freunden.",
+  "ONBOARDING_3_TITLE": "2. Video auswählen",
+  "ONBOARDING_3_TEXT": "Wähle hier das Video aus, das du synchronisieren willst. Abspielen, Pause, Spulen — alle bleiben synchron.",
+  "ONBOARDING_4_TITLE": "3. Personalisieren",
+  "ONBOARDING_4_TEXT": "Wähle einen lustigen Benutzernamen, damit deine Freunde wissen, wer du bist.",
+  "ONBOARDING_5_TITLE": "Alles startklar!",
+  "ONBOARDING_5_TEXT": "Zeit, das Popcorn zu holen. Viel Spaß beim gemeinsamen Schauen!",
+  "ERR_CONN_TIMEOUT": "Verbindung abgelaufen. Bitte versuche es erneut.",
+  "ERR_INVALID_SERVER_URL": "Ungültiges Server-URL-Format.",
+  "ERR_IDENTITY_NOT_LOADED": "Identität noch nicht geladen. Warte kurz und versuche es erneut.",
+  "ERR_NO_PEERS_TIME": "Keine anderen Teilnehmer mit bekannter Zeit. Wechsle zu 'Zu mir springen'.",
+  "ERR_NO_VIDEO_TAB": "Verbindung zum Video-Tab fehlgeschlagen.",
+  "SITE_ACCESS_REQUIRED": "Dein Browser blockiert KoalaSync auf {host}. Klicke unten auf „Zugriff erlauben“. Falls kein Dialog erscheint, erlaube KoalaSync in den Erweiterungs- oder Websiteberechtigungen für diese Seite.",
+  "BTN_RETRY_ACCESS": "Zugriff erlauben",
+  "ERR_SELECT_VIDEO": "Bitte wähle zuerst ein Video aus!",
+  "TOAST_INVITE_COPIED": "Einladungslink kopiert!",
+  "TOAST_COPY_FAILED": "Kopieren in Zwischenablage fehlgeschlagen",
+  "TOAST_LOBBY_SKIPPED": "Episoden-Lobby übersprungen.",
+  "TOAST_LOBBY_SKIP_FAILED": "Überspringen der Lobby fehlgeschlagen.",
+  "TOAST_LOGS_COPIED": "Kopiert!",
+  "TOAST_PEER_JOINED": "{name} ist dem Raum beigetreten",
+  "TOAST_PEER_LEFT": "{name} hat den Raum verlassen",
+  "TOAST_PEER_ACTION": "{name} hat {action}",
+  "STATUS_CONNECTED": "Verbunden",
+  "STATUS_RECONNECTING": "Verbinde erneut...",
+  "STATUS_CONNECTING": "Verbinde...",
+  "STATUS_FAILED": "Fehlgeschlagen",
+  "STATUS_DISCONNECTED": "Getrennt",
+  "STATUS_IDLE": "Bereit zum Verbinden",
+  "STATUS_IDLE_TOOLTIP": "KoalaSync ist bereit. Tritt einem Raum bei oder erstelle einen, um die Verbindung herzustellen und die Synchronisierung zu starten.",
+  "BTN_STATE_JOINING": "🚀 Trete bei...",
+  "BTN_STATE_RECONNECTING": "🔄 Verbinde erneut...",
+  "BTN_STATE_PLAYING": "▶ Spiele ab...",
+  "BTN_STATE_PAUSING": "⏸ Pausiere...",
+  "BTN_STATE_SYNCING_GROUP": "Synce zur Gruppe ({time})...",
+  "BTN_STATE_SYNCING": "Synchronisiere...",
+  "BTN_STATE_SYNCED": "✅ Synchronisiert!",
+  "NOTIF_PLAY": "die Wiedergabe gestartet",
+  "NOTIF_PAUSE": "die Wiedergabe pausiert",
+  "NOTIF_SEEK": "im Video gespult",
+  "NOTIF_FORCE_PREPARE": "eine erzwungene Synchronisation gestartet",
+  "NOTIF_FORCE_EXECUTE": "alle Teilnehmer synchronisiert",
+  "DEBUG_NO_TAB": "Kein Ziel-Tab ausgewählt.",
+  "DEBUG_COMM_FAIL": "Kommunikation mit dem Tab-Video fehlgeschlagen.",
+  "EMPTY_PEERS_TITLE": "Noch keine Teilnehmer",
+  "EMPTY_PEERS_HINT": "Teile deinen Einladungslink, um loszulegen",
+  "EMPTY_HISTORY_TITLE": "Noch keine Aktivität",
+  "EMPTY_HISTORY_HINT": "Abspielen, Pausieren oder Spulen, um Verlauf zu sehen",
+  "EMPTY_LOGS_TITLE": "Keine Logs",
+  "EMPTY_LOGS_HINT": "Verbindungsereignisse werden hier angezeigt",
+  "EMPTY_ROOMS_TITLE": "Keine aktiven Räume",
+  "EMPTY_ROOMS_HINT": "Raum erstellen oder aktualisieren, um öffentliche zu finden",
+  "LABEL_YOU": "Du",
+  "ONBOARDING_DONE": "Fertig!",
+  "LABEL_LOBBY_PEER_READY": "Bereit",
+  "LABEL_LOBBY_PEER_LOADING": "Lädt...",
+  "LABEL_PASSWORD_PROTECTED": "Passwortgeschützt",
+  "LABEL_PEERS_COUNT": "{count} Teilnehmer",
+  "LABEL_CUSTOM_SERVER": "Eigener Server",
+  "BTN_STATE_CREATING": "🚀 Erstelle Raum...",
+  "NOTIF_LOBBY_CANCEL_TITLE": "KoalaSync — Episoden-Synchronisation fehlgeschlagen",
+  "NOTIF_LOBBY_CANCEL_MSG": "Auto-Sync abgebrochen: {reason}. Du musst eventuell manuell synchronisieren.",
+  "LOBBY_CANCEL_TIMEOUT": "Zeitüberschreitung",
+  "LOBBY_CANCEL_TIMEOUT_RECOVERED": "Zeitüberschreitung (wiederhergestellt)",
+  "LOBBY_CANCEL_PEERS_LEFT": "Alle anderen Teilnehmer haben den Raum verlassen",
+  "LOBBY_CANCEL_TIMEOUT_PEERS_LOAD": "Zeitüberschreitung — nicht alle Teilnehmer haben die Episode geladen",
+  "LOBBY_CANCEL_USER": "Vom Benutzer abgebrochen",
+  "NOTIF_ERROR_TITLE": "KoalaSync-Fehler",
+  "FOOTER_SUPPORT": "Support KoalaSync",
+  "FOOTER_REVIEW": "★ Bewerten",
+  "FOOTER_SUPPORT_PROMPT": "Gefällt dir KoalaSync? Hinterlasse eine Bewertung!",
+  "LABEL_AUDIO_PROCESSING": "Audio-Verarbeitung",
+  "LABEL_AUDIO_PROCESSING_TOOLTIP": "Wendet Audioeffekte wie Kompression auf die Videowiedergabe an",
+  "AUDIO_OPEN_SETTINGS": "Öffnen",
+  "NEW_FEATURE_AUDIO": "Neu: Audio-Verarbeitung — probiere den Kompressor aus!",
+  "NEW_FEATURE_THEME": "Neu: Themes — wechsle zum klassischen Look oder minimalem Graphit.",
+  "AUDIO_BACK": "← Zurück",
+  "AUDIO_PAGE_TITLE": "Audio-Einstellungen",
+  "AUDIO_MASTER_TOGGLE": "Audio-Verarbeitung",
+  "AUDIO_COMPRESSOR": "Kompressor",
+  "AUDIO_COMPRESSOR_ENABLE": "Aktiviert",
+  "AUDIO_PRESET": "Preset",
+  "AUDIO_PRESET_RECOMMENDED": "Empfohlen",
+  "AUDIO_PRESET_DYNAMIC_RANGE": "Dynamikumfang",
+  "AUDIO_PRESET_VOCAL_ENHANCEMENT": "Sprache verbessern",
+  "AUDIO_PRESET_SMOOTH": "Sanft",
+  "AUDIO_PRESET_CUSTOM": "Benutzerdefiniert",
+  "AUDIO_PARAM_THRESHOLD": "Schwellwert",
+  "AUDIO_PARAM_KNEE": "Knee",
+  "AUDIO_PARAM_RATIO": "Ratio",
+  "AUDIO_PARAM_ATTACK": "Attack",
+  "AUDIO_PARAM_RELEASE": "Release",
+  "AUDIO_EQUALIZER": "Equalizer",
+  "AUDIO_COMING_SOON": "Demnächst",
+  "BTN_RESTART_TOUR": "Einführung neu starten",
+  "BTN_RESTART_TOUR_TOOLTIP": "Startet die Einführung für neue Benutzer erneut",
+  "HINT_SELECT_VIDEO": "Wähle hier dein Video aus!",
+  "OPTION_TITLE_PRIVACY_FULL": "Voll senden",
+  "OPTION_TITLE_PRIVACY_EPISODE": "Nur Episoden-ID senden",
+  "OPTION_TITLE_PRIVACY_HIDDEN": "Nicht senden",
+  "LABEL_PRIVACY_SETTINGS": "Privatsphäre-Einstellungen",
+  "LABEL_PRIVACY_SETTINGS_TOOLTIP": "Lege fest, welche Tab- und Medientitel an den Raum gesendet werden.",
+  "LABEL_SEND_TAB_TITLE": "Tab-Titel senden",
+  "LABEL_SEND_TAB_TITLE_TOOLTIP": "Sendet den Titel des ausgewählten Browser-Tabs an den Raum.",
+  "LABEL_MEDIA_TITLE_PRIVACY": "Medientitel",
+  "LABEL_MEDIA_TITLE_PRIVACY_TOOLTIP": "Lege fest, wie Medientitel an den Raum gesendet werden.",
+  "LABEL_SETTINGS_GROUP_PROFILE": "Profil & Aussehen",
+  "LABEL_SETTINGS_GROUP_PROFILE_TOOLTIP": "Ändere deinen Benutzernamen, dein Design und deine Spracheinstellungen.",
+  "LABEL_SETTINGS_GROUP_SYNC": "Wiedergabe & Sync",
+  "LABEL_SETTINGS_GROUP_SYNC_TOOLTIP": "Passe Wiedergabe-, Benachrichtigungs- und Audioeinstellungen an."
+}

extension/locales/en.json

@@ -0,0 +1,249 @@
+{
+  "LANG_CODE": "en",
+  "HTML_CLASS": "lang-en",
+  "APP_TITLE": "KoalaSync",
+  "TAB_ROOM": "Room",
+  "TAB_ROOM_TOOLTIP": "Room settings and connection",
+  "TAB_SYNC": "Sync",
+  "TAB_SYNC_TOOLTIP": "Video sync controls and remote actions",
+  "TAB_SETTINGS": "Settings",
+  "TAB_SETTINGS_TOOLTIP": "Extension preferences",
+  "TAB_STATUS": "Status",
+  "TAB_STATUS_TOOLTIP": "Advanced Diagnostics & Logs",
+  "BTN_CREATE_ROOM": "+ Create New Room",
+  "MANUAL_CONNECT_HEADER": "Manual Connect / Advanced",
+  "LABEL_SERVER": "Server",
+  "BTN_SERVER_OFFICIAL": "Official",
+  "BTN_SERVER_OFFICIAL_TOOLTIP": "Use the official reliable server",
+  "BTN_SERVER_CUSTOM": "Custom",
+  "BTN_SERVER_CUSTOM_TOOLTIP": "Connect to your own self-hosted server",
+  "PLACEHOLDER_SERVER_URL": "wss://your-server:3000",
+  "LABEL_ROOM_ID": "Room ID",
+  "LABEL_ROOM_ID_TOOLTIP": "The unique identifier for your sync room",
+  "PLACEHOLDER_ROOM_ID": "Enter Room ID",
+  "PLACEHOLDER_ROOM_ID_TOOLTIP": "The unique ID of the room you want to join",
+  "LABEL_PASSWORD": "Password (Optional)",
+  "LABEL_PASSWORD_TOOLTIP": "Optional password to restrict room access",
+  "PLACEHOLDER_PASSWORD": "Room Password (optional)",
+  "PLACEHOLDER_PASSWORD_TOOLTIP": "Password for the room (leave empty if none)",
+  "BTN_JOIN_ROOM": "Join / Create Room",
+  "BTN_JOIN_ROOM_TOOLTIP": "Connect to the room",
+  "LABEL_PUBLIC_ROOMS": "Public Rooms",
+  "LABEL_PUBLIC_ROOMS_TOOLTIP": "List of publicly available rooms on this server",
+  "BTN_REFRESH": "REFRESH",
+  "BTN_REFRESH_TOOLTIP": "Refresh the list of public rooms",
+  "PUBLIC_ROOMS_REFRESHING": "Refreshing...",
+  "BTN_REFRESH_COOLDOWN": "WAIT {seconds}s",
+  "BTN_REFRESH_COOLDOWN_TOOLTIP": "Room list refresh is cooling down. Try again in {seconds}s.",
+  "PUBLIC_ROOMS_REFRESHING_COOLDOWN": "Refreshing public rooms. Next refresh available in {seconds}s.",
+  "LABEL_ACTIVE_ROOM": "Active Room",
+  "LABEL_ACTIVE_ROOM_TOOLTIP": "The room you are currently connected to",
+  "ACTIVE_ROOM_NONE": "NONE",
+  "ACTIVE_SERVER_OFFICIAL": "Official Server",
+  "LABEL_INVITE_LINK": "Invite Link",
+  "LABEL_INVITE_LINK_TOOLTIP": "Share this link with friends so they can join",
+  "LABEL_PEERS_IN_ROOM": "Peers in Room",
+  "LABEL_PEERS_IN_ROOM_TOOLTIP": "Other users currently connected to this room",
+  "LABEL_HOST_CONTROL": "Host Control",
+  "LABEL_HOST_CONTROL_TOOLTIP": "Restrict who can control playback in this room",
+  "LABEL_HOST_ONLY_TOGGLE": "Only I can control playback",
+  "NOTICE_HOST_CONTROLS": "The host controls playback for everyone.",
+  "NOTICE_COHOST_HINT": "Tip: grant control to individual viewers in the participant list below.",
+  "BADGE_HOST": "Host",
+  "BADGE_GUEST": "Guest",
+  "BADGE_CONTROLLER": "Controller",
+  "BTN_GIVE_CONTROL": "Give control",
+  "BTN_REVOKE_CONTROL": "Revoke",
+  "BADGE_DESYNCED": "Solo",
+  "TOOLTIP_PEER_DESYNCED": "Watching on their own — host's commands are ignored",
+  "HCM_DIALOG_TITLE": "KoalaSync · Host controls this room",
+  "HCM_DIALOG_BODY": "Only the host can control playback in this room. Keep watching together, or watch on your own?",
+  "HCM_DIALOG_STAY": "Stay in sync",
+  "HCM_DIALOG_SOLO": "Watch on my own",
+  "HCM_BADGE_SOLO": "Watching on your own",
+  "HCM_BADGE_RESYNC": "Resync",
+  "NO_PEERS_CONNECTED": "No peers connected",
+  "BTN_LEAVE_ROOM": "Leave Room",
+  "LABEL_SELECT_VIDEO": "Select Video",
+  "LABEL_SELECT_VIDEO_TOOLTIP": "Choose the browser tab containing the video to sync",
+  "OPTION_SELECT_TAB": "-- Select a Tab --",
+  "LABEL_REMOTE_CONTROL": "Remote Control",
+  "BTN_COPY_INVITE": "📋 Invite Link",
+  "BTN_COPY_INVITE_TOOLTIP": "Copy Invite Link",
+  "BTN_PLAY": "Play",
+  "BTN_PLAY_TOOLTIP": "Send a Play command to everyone",
+  "BTN_PAUSE": "Pause",
+  "BTN_PAUSE_TOOLTIP": "Send a Pause command to everyone",
+  "BTN_SYNC": "Sync",
+  "BTN_SYNC_TOOLTIP": "Force all users to sync up",
+  "OPTION_JUMP_TO_OTHERS": "Jump to Others",
+  "OPTION_JUMP_TO_ME": "Jump to Me",
+  "OPTION_JUMP_MODE_TOOLTIP": "Choose sync target",
+  "LABEL_LAST_ACTIVITY": "Last Activity Status",
+  "LABEL_LAST_ACTIVITY_TOOLTIP": "Shows the most recent play, pause, or seek command",
+  "NO_RECENT_COMMANDS": "No recent commands",
+  "LOBBY_HEADER": "EPISODE LOBBY",
+  "LOBBY_WAITING_FOR": "🎬 Waiting for: \"{title}\"",
+  "LOBBY_WAITING_PEERS": "Waiting for peers...",
+  "BTN_SKIP_PLAY": "Skip & Play anyway",
+  "BTN_SKIP_PLAY_TOOLTIP": "Cancel lobby and play anyway",
+  "LOBBY_CONNECT_FIRST": "Connect to a room first",
+  "LOBBY_CONNECT_FIRST_DESC": "You need to join a room via an invite link or create a new one to sync videos.",
+  "BTN_CREATE_ROOM_ALT": "Create New Room",
+  "BTN_CREATE_ROOM_ALT_TOOLTIP": "Create a new random room and join it",
+  "LABEL_USERNAME": "Your Username",
+  "LABEL_USERNAME_TOOLTIP": "Username helps others identify you.",
+  "PLACEHOLDER_USERNAME": "Anonymous Koala",
+  "LABEL_HIDE_CLUTTER": "Hide Clutter Tabs",
+  "LABEL_HIDE_CLUTTER_TOOLTIP": "Filters out non-video tabs and unrelated domains to keep the list clean",
+  "LABEL_AUTO_SYNC_NEXT": "Auto-Sync Next Episode",
+  "LABEL_AUTO_SYNC_NEXT_TOOLTIP": "Pauses automatically and waits for all peers when an episode changes, then sync-starts together.",
+  "LABEL_AUTO_COPY_INVITE": "Auto-Copy Invite Link",
+  "LABEL_AUTO_COPY_INVITE_TOOLTIP": "Automatically copies the invite link to your clipboard when creating a new room.",
+  "LABEL_NOTIFICATIONS": "Browser Notifications",
+  "LABEL_NOTIFICATIONS_TOOLTIP": "Shows native system notifications when someone joins/leaves or plays/pauses.",
+  "LABEL_LANGUAGE": "App Language",
+  "LABEL_LANGUAGE_TOOLTIP": "Choose your preferred extension language",
+  "LABEL_TROUBLESHOOTING": "Troubleshooting",
+  "LABEL_TROUBLESHOOTING_TOOLTIP": "Tools for fixing connection issues",
+  "BTN_REGEN_ID": "Regenerate Peer ID",
+  "BTN_REGEN_ID_TOOLTIP": "Regenerate your internal ID and reconnect",
+  "REGEN_ID_DESC": "Use this if you see \"Duplicate Identity\" errors.",
+  "REGEN_ID_OTHER_ISSUE": "Other issue? Open a GitHub Issue",
+  "TOAST_ID_REGENERATED": "Identity regenerated — reconnecting…",
+  "LABEL_CONN_STATUS": "Connection Status",
+  "LABEL_CONN_STATUS_TOOLTIP": "Current WebSocket connection state",
+  "CONN_STATUS_DISCONNECTED": "Disconnected",
+  "BTN_RETRY": "RETRY",
+  "BTN_RETRY_TOOLTIP": "Attempt to reconnect to the server",
+  "BTN_COPY_LOGS": "Copy Logs",
+  "BTN_COPY_LOGS_TOOLTIP": "Copy logs to clipboard for sharing",
+  "LABEL_VIDEO_DEBUG": "Video Debug Info",
+  "LABEL_VIDEO_DEBUG_TOOLTIP": "Technical details about the currently selected video element",
+  "VIDEO_DEBUG_EMPTY": "No tab selected or video detected.",
+  "LABEL_HISTORY": "Full Action History",
+  "LABEL_HISTORY_TOOLTIP": "Chronological log of all sync commands in the room",
+  "HISTORY_EMPTY": "No activity yet",
+  "LABEL_LOGS": "Logs (Last 50)",
+  "LABEL_LOGS_TOOLTIP": "Technical connection logs for debugging",
+  "BTN_CLEAR": "CLEAR",
+  "BTN_CLEAR_TOOLTIP": "Clear log output",
+  "LABEL_GITHUB": "GitHub Repository",
+  "BTN_ONBOARDING_SKIP": "Skip",
+  "BTN_ONBOARDING_SKIP_TOOLTIP": "Skip the tutorial",
+  "BTN_ONBOARDING_NEXT": "Next",
+  "BTN_ONBOARDING_NEXT_TOOLTIP": "Go to next step",
+  "ONBOARDING_1_TITLE": "Welcome to KoalaSync!",
+  "ONBOARDING_1_TEXT": "Watch videos together in perfect sync — no matter where you are. Let's take a quick tour!",
+  "ONBOARDING_2_TITLE": "1. Create a Room",
+  "ONBOARDING_2_TEXT": "Start here. Create a room and share the invite link with your friends.",
+  "ONBOARDING_3_TITLE": "2. Select Video",
+  "ONBOARDING_3_TEXT": "Navigate here to select the video you want to sync. Play, pause, and seek — everyone stays in sync.",
+  "ONBOARDING_4_TITLE": "3. Personalize",
+  "ONBOARDING_4_TEXT": "Pick a fun username so your friends know who you are.",
+  "ONBOARDING_5_TITLE": "You're all set!",
+  "ONBOARDING_5_TEXT": "Time to grab some popcorn. Enjoy watching together!",
+  "ERR_CONN_TIMEOUT": "Connection timed out. Please try again.",
+  "ERR_INVALID_SERVER_URL": "Invalid Server URL format.",
+  "ERR_IDENTITY_NOT_LOADED": "Identity not yet loaded. Wait a moment and try again.",
+  "ERR_NO_PEERS_TIME": "No other peers with a known time. Switch to 'Jump to Me'.",
+  "ERR_NO_VIDEO_TAB": "Could not connect to video tab.",
+  "SITE_ACCESS_REQUIRED": "Your browser is blocking KoalaSync on {host}. Click \"Allow access\" below. If no dialog appears, allow KoalaSync on this site in your extension or site permissions.",
+  "BTN_RETRY_ACCESS": "Allow access",
+  "ERR_SELECT_VIDEO": "Please select a video first!",
+  "TOAST_INVITE_COPIED": "Invite link copied!",
+  "TOAST_COPY_FAILED": "Failed to copy to clipboard",
+  "TOAST_LOBBY_SKIPPED": "Episode Lobby skipped.",
+  "TOAST_LOBBY_SKIP_FAILED": "Failed to skip lobby.",
+  "TOAST_LOGS_COPIED": "Copied!",
+  "TOAST_PEER_JOINED": "{name} joined the room",
+  "TOAST_PEER_LEFT": "{name} left the room",
+  "TOAST_PEER_ACTION": "{name} {action}",
+  "STATUS_CONNECTED": "Connected",
+  "STATUS_RECONNECTING": "Reconnecting...",
+  "STATUS_CONNECTING": "Connecting...",
+  "STATUS_FAILED": "Failed",
+  "STATUS_DISCONNECTED": "Disconnected",
+  "STATUS_IDLE": "Ready to connect",
+  "STATUS_IDLE_TOOLTIP": "KoalaSync is ready. Join or create a room to connect and start syncing.",
+  "BTN_STATE_JOINING": "🚀 Joining...",
+  "BTN_STATE_RECONNECTING": "🔄 Reconnecting...",
+  "BTN_STATE_PLAYING": "▶ Playing...",
+  "BTN_STATE_PAUSING": "⏸ Pausing...",
+  "BTN_STATE_SYNCING_GROUP": "Syncing to group ({time})...",
+  "BTN_STATE_SYNCING": "Syncing...",
+  "BTN_STATE_SYNCED": "✅ Synced!",
+  "NOTIF_PLAY": "started playback",
+  "NOTIF_PAUSE": "paused playback",
+  "NOTIF_SEEK": "seeked the video",
+  "NOTIF_FORCE_PREPARE": "started force sync",
+  "NOTIF_FORCE_EXECUTE": "synchronized everyone",
+  "DEBUG_NO_TAB": "No target tab selected.",
+  "DEBUG_COMM_FAIL": "Could not communicate with tab video.",
+  "EMPTY_PEERS_TITLE": "No peers yet",
+  "EMPTY_PEERS_HINT": "Share your invite link to get started",
+  "EMPTY_HISTORY_TITLE": "No activity yet",
+  "EMPTY_HISTORY_HINT": "Play, pause, or seek to see history",
+  "EMPTY_LOGS_TITLE": "No logs",
+  "EMPTY_LOGS_HINT": "Connection events will appear here",
+  "EMPTY_ROOMS_TITLE": "No active rooms",
+  "EMPTY_ROOMS_HINT": "Create a room or refresh to find public ones",
+  "LABEL_YOU": "You",
+  "ONBOARDING_DONE": "Done!",
+  "LABEL_LOBBY_PEER_READY": "Ready",
+  "LABEL_LOBBY_PEER_LOADING": "Loading...",
+  "LABEL_PASSWORD_PROTECTED": "Password Protected",
+  "LABEL_PEERS_COUNT": "{count} peers",
+  "LABEL_CUSTOM_SERVER": "Custom Server",
+  "BTN_STATE_CREATING": "🚀 Creating Room...",
+  "NOTIF_LOBBY_CANCEL_TITLE": "KoalaSync — Episode Sync Failed",
+  "NOTIF_LOBBY_CANCEL_MSG": "Auto-sync cancelled: {reason}. You may need to manually sync.",
+  "LOBBY_CANCEL_TIMEOUT": "Timeout",
+  "LOBBY_CANCEL_TIMEOUT_RECOVERED": "Timeout (recovered)",
+  "LOBBY_CANCEL_PEERS_LEFT": "All other peers left",
+  "LOBBY_CANCEL_TIMEOUT_PEERS_LOAD": "Timeout — not all peers loaded the episode",
+  "LOBBY_CANCEL_USER": "Cancelled by user",
+  "NOTIF_ERROR_TITLE": "KoalaSync Error",
+  "FOOTER_SUPPORT": "Support KoalaSync",
+  "FOOTER_REVIEW": "★ Rate us",
+  "FOOTER_SUPPORT_PROMPT": "Enjoying KoalaSync? Leave a review!",
+  "LABEL_AUDIO_PROCESSING": "Audio Processing",
+  "LABEL_AUDIO_PROCESSING_TOOLTIP": "Apply audio effects like compression to video playback",
+  "AUDIO_OPEN_SETTINGS": "Open",
+  "NEW_FEATURE_AUDIO": "New: Audio Processing — try the compressor!",
+  "NEW_FEATURE_THEME": "New: Themes — switch to the classic look or minimal graphite.",
+  "AUDIO_BACK": "← Back",
+  "AUDIO_PAGE_TITLE": "Audio Settings",
+  "AUDIO_MASTER_TOGGLE": "Audio Processing",
+  "AUDIO_COMPRESSOR": "Compressor",
+  "AUDIO_COMPRESSOR_ENABLE": "Enabled",
+  "AUDIO_PRESET": "Preset",
+  "AUDIO_PRESET_RECOMMENDED": "Recommended",
+  "AUDIO_PRESET_DYNAMIC_RANGE": "Dynamic Range",
+  "AUDIO_PRESET_VOCAL_ENHANCEMENT": "Vocal Enhancement",
+  "AUDIO_PRESET_SMOOTH": "Smooth",
+  "AUDIO_PRESET_CUSTOM": "Custom",
+  "AUDIO_PARAM_THRESHOLD": "Threshold",
+  "AUDIO_PARAM_KNEE": "Knee",
+  "AUDIO_PARAM_RATIO": "Ratio",
+  "AUDIO_PARAM_ATTACK": "Attack",
+  "AUDIO_PARAM_RELEASE": "Release",
+  "AUDIO_EQUALIZER": "Equalizer",
+  "AUDIO_COMING_SOON": "Coming soon",
+  "BTN_RESTART_TOUR": "Restart Tutorial",
+  "BTN_RESTART_TOUR_TOOLTIP": "Restart the onboarding tutorial",
+  "HINT_SELECT_VIDEO": "Select your video here!",
+  "OPTION_TITLE_PRIVACY_FULL": "Send full title",
+  "OPTION_TITLE_PRIVACY_EPISODE": "Send episode ID",
+  "OPTION_TITLE_PRIVACY_HIDDEN": "Do not send",
+  "LABEL_PRIVACY_SETTINGS": "Privacy Settings",
+  "LABEL_PRIVACY_SETTINGS_TOOLTIP": "Choose which tab and media titles are sent to the room.",
+  "LABEL_SEND_TAB_TITLE": "Send tab title",
+  "LABEL_SEND_TAB_TITLE_TOOLTIP": "Send the selected browser tab title to the room.",
+  "LABEL_MEDIA_TITLE_PRIVACY": "Media title",
+  "LABEL_MEDIA_TITLE_PRIVACY_TOOLTIP": "Choose how media titles are sent to the room.",
+  "LABEL_SETTINGS_GROUP_PROFILE": "Profile & Appearance",
+  "LABEL_SETTINGS_GROUP_PROFILE_TOOLTIP": "Change your username, theme, and language preferences.",
+  "LABEL_SETTINGS_GROUP_SYNC": "Playback & Sync",
+  "LABEL_SETTINGS_GROUP_SYNC_TOOLTIP": "Customize playback, notifications, and audio preferences."
+}

extension/locales/es.json

@@ -0,0 +1,249 @@
+{
+  "LANG_CODE": "es",
+  "HTML_CLASS": "lang-es",
+  "APP_TITLE": "KoalaSync",
+  "TAB_ROOM": "Sala",
+  "TAB_ROOM_TOOLTIP": "Configuración de sala y conexión",
+  "TAB_SYNC": "Sincro",
+  "TAB_SYNC_TOOLTIP": "Controles de sincronización de video y acciones",
+  "TAB_SETTINGS": "Configuración",
+  "TAB_SETTINGS_TOOLTIP": "Preferencias de la extensión",
+  "TAB_STATUS": "Estado",
+  "TAB_STATUS_TOOLTIP": "Diagnósticos avanzados y registros",
+  "BTN_CREATE_ROOM": "+ Crear nueva sala",
+  "MANUAL_CONNECT_HEADER": "Conexión manual / Avanzado",
+  "LABEL_SERVER": "Servidor",
+  "BTN_SERVER_OFFICIAL": "Oficial",
+  "BTN_SERVER_OFFICIAL_TOOLTIP": "Usar el servidor oficial confiable",
+  "BTN_SERVER_CUSTOM": "Personalizado",
+  "BTN_SERVER_CUSTOM_TOOLTIP": "Conectarse a su propio servidor auto-alojado",
+  "PLACEHOLDER_SERVER_URL": "wss://tu-servidor:3000",
+  "LABEL_ROOM_ID": "ID de sala",
+  "LABEL_ROOM_ID_TOOLTIP": "El identificador único para tu sala de sincronización",
+  "PLACEHOLDER_ROOM_ID": "Ingresa el ID de la sala",
+  "PLACEHOLDER_ROOM_ID_TOOLTIP": "El ID único de la sala a la que deseas unirte",
+  "LABEL_PASSWORD": "Contraseña (Opcional)",
+  "LABEL_PASSWORD_TOOLTIP": "Contraseña opcional para restringir el acceso a la sala",
+  "PLACEHOLDER_PASSWORD": "Contraseña de la sala (opcional)",
+  "PLACEHOLDER_PASSWORD_TOOLTIP": "Contraseña para la sala (dejar vacío si no hay)",
+  "BTN_JOIN_ROOM": "Unirse / Crear sala",
+  "BTN_JOIN_ROOM_TOOLTIP": "Conectarse a la sala",
+  "LABEL_PUBLIC_ROOMS": "Salas públicas",
+  "LABEL_PUBLIC_ROOMS_TOOLTIP": "Lista de salas públicas disponibles en este servidor",
+  "BTN_REFRESH": "ACTUALIZAR",
+  "BTN_REFRESH_TOOLTIP": "Actualizar la lista de salas públicas",
+  "PUBLIC_ROOMS_REFRESHING": "Actualizando...",
+  "BTN_REFRESH_COOLDOWN": "ESPERA {seconds}s",
+  "BTN_REFRESH_COOLDOWN_TOOLTIP": "La lista de salas está en espera. Inténtalo de nuevo en {seconds}s.",
+  "PUBLIC_ROOMS_REFRESHING_COOLDOWN": "Actualizando salas públicas. Próxima actualización en {seconds}s.",
+  "LABEL_ACTIVE_ROOM": "Sala activa",
+  "LABEL_ACTIVE_ROOM_TOOLTIP": "La sala a la que estás conectado actualmente",
+  "ACTIVE_ROOM_NONE": "NINGUNA",
+  "ACTIVE_SERVER_OFFICIAL": "Servidor oficial",
+  "LABEL_INVITE_LINK": "Enlace de invitación",
+  "LABEL_INVITE_LINK_TOOLTIP": "Comparte este enlace con amigos para que se unan",
+  "LABEL_PEERS_IN_ROOM": "Participantes en la sala",
+  "LABEL_PEERS_IN_ROOM_TOOLTIP": "Otros usuarios conectados actualmente a esta sala",
+  "LABEL_HOST_CONTROL": "Control del anfitrión",
+  "LABEL_HOST_CONTROL_TOOLTIP": "Restringir quién puede controlar la reproducción en esta sala",
+  "LABEL_HOST_ONLY_TOGGLE": "Solo yo puedo controlar la reproducción",
+  "NOTICE_HOST_CONTROLS": "El anfitrión controla la reproducción para todos.",
+  "NOTICE_COHOST_HINT": "Consejo: concede el control a usuarios concretos en la lista de participantes de abajo.",
+  "BADGE_HOST": "Anfitrión",
+  "BADGE_GUEST": "Invitado",
+  "BADGE_CONTROLLER": "Controlador",
+  "BTN_GIVE_CONTROL": "Dar control",
+  "BTN_REVOKE_CONTROL": "Quitar",
+  "BADGE_DESYNCED": "Solo",
+  "TOOLTIP_PEER_DESYNCED": "Viendo por su cuenta — ignora los comandos del anfitrión",
+  "HCM_DIALOG_TITLE": "KoalaSync · El anfitrión controla esta sala",
+  "HCM_DIALOG_BODY": "Solo el anfitrión puede controlar la reproducción en esta sala. ¿Seguir viendo juntos o ver por tu cuenta?",
+  "HCM_DIALOG_STAY": "Seguir sincronizado",
+  "HCM_DIALOG_SOLO": "Ver por mi cuenta",
+  "HCM_BADGE_SOLO": "Viendo por tu cuenta",
+  "HCM_BADGE_RESYNC": "Resincronizar",
+  "NO_PEERS_CONNECTED": "Sin participantes conectados",
+  "BTN_LEAVE_ROOM": "Salir de la sala",
+  "LABEL_SELECT_VIDEO": "Seleccionar video",
+  "LABEL_SELECT_VIDEO_TOOLTIP": "Elige la pestaña del navegador que contiene el video a sincronizar",
+  "OPTION_SELECT_TAB": "-- Selecciona una pestaña --",
+  "LABEL_REMOTE_CONTROL": "Control remoto",
+  "BTN_COPY_INVITE": "📋 Enlace de invitación",
+  "BTN_COPY_INVITE_TOOLTIP": "Copiar enlace de invitación",
+  "BTN_PLAY": "Reproducir",
+  "BTN_PLAY_TOOLTIP": "Enviar un comando de reproducción a todos",
+  "BTN_PAUSE": "Pausar",
+  "BTN_PAUSE_TOOLTIP": "Enviar un comando de pausa a todos",
+  "BTN_SYNC": "Sync",
+  "BTN_SYNC_TOOLTIP": "Forzar la sincronización de todos los usuarios",
+  "OPTION_JUMP_TO_OTHERS": "Ir a la posición de otros",
+  "OPTION_JUMP_TO_ME": "Traerlos a mi posición",
+  "OPTION_JUMP_MODE_TOOLTIP": "Elegir el objetivo de sincronización",
+  "LABEL_LAST_ACTIVITY": "Última actividad",
+  "LABEL_LAST_ACTIVITY_TOOLTIP": "Muestra el comando más reciente de reproducción, pausa o salto en el tiempo",
+  "NO_RECENT_COMMANDS": "Sin comandos recientes",
+  "LOBBY_HEADER": "SALA DE ESPERA DE EPISODIO",
+  "LOBBY_WAITING_FOR": "🎬 Esperando a: \"{title}\"",
+  "LOBBY_WAITING_PEERS": "Esperando participantes...",
+  "BTN_SKIP_PLAY": "Omitir y reproducir ya",
+  "BTN_SKIP_PLAY_TOOLTIP": "Cancelar la sala de espera y reproducir de todos modos",
+  "LOBBY_CONNECT_FIRST": "Únete a una sala primero",
+  "LOBBY_CONNECT_FIRST_DESC": "Necesitas unirte a una sala a través de un enlace de invitación o crear una nueva para sincronizar videos.",
+  "BTN_CREATE_ROOM_ALT": "Crear nueva sala",
+  "BTN_CREATE_ROOM_ALT_TOOLTIP": "Crear una nueva sala aleatoria y unirse",
+  "LABEL_USERNAME": "Tu nombre de usuario",
+  "LABEL_USERNAME_TOOLTIP": "El nombre de usuario ayuda a otros a identificarte.",
+  "PLACEHOLDER_USERNAME": "Koala anónimo",
+  "LABEL_HIDE_CLUTTER": "Ocultar pestañas sin video",
+  "LABEL_HIDE_CLUTTER_TOOLTIP": "Filtra pestañas que no son de video y dominios no relacionados para mantener limpia la lista",
+  "LABEL_AUTO_SYNC_NEXT": "Sincro auto del siguiente episodio",
+  "LABEL_AUTO_SYNC_NEXT_TOOLTIP": "Pausa automáticamente y espera a todos al cambiar de episodio, luego inicia de forma sincrónica.",
+  "LABEL_AUTO_COPY_INVITE": "Auto-copiar enlace",
+  "LABEL_AUTO_COPY_INVITE_TOOLTIP": "Copia automáticamente el enlace de invitación a tu portapapeles al crear una nueva sala.",
+  "LABEL_NOTIFICATIONS": "Notificaciones del navegador",
+  "LABEL_NOTIFICATIONS_TOOLTIP": "Muestra notificaciones del sistema cuando alguien se une/sale o reproduce/pausa.",
+  "LABEL_LANGUAGE": "Idioma de la aplicación",
+  "LABEL_LANGUAGE_TOOLTIP": "Elige tu idioma preferido para la extensión",
+  "LABEL_TROUBLESHOOTING": "Resolución de problemas",
+  "LABEL_TROUBLESHOOTING_TOOLTIP": "Herramientas para solucionar problemas de conexión",
+  "BTN_REGEN_ID": "Regenerar ID de usuario",
+  "BTN_REGEN_ID_TOOLTIP": "Regenerar tu ID interno y volver a conectarte",
+  "REGEN_ID_DESC": "Usa esto si ves errores de 'Identidad duplicada'.",
+  "REGEN_ID_OTHER_ISSUE": "¿Tienes otro problema? Abre un reporte en GitHub",
+  "TOAST_ID_REGENERATED": "Identidad regenerada — reconectando…",
+  "LABEL_CONN_STATUS": "Estado de la conexión",
+  "LABEL_CONN_STATUS_TOOLTIP": "Estado actual de la conexión WebSocket",
+  "CONN_STATUS_DISCONNECTED": "Desconectado",
+  "BTN_RETRY": "REINTENTAR",
+  "BTN_RETRY_TOOLTIP": "Intentar volver a conectarse al servidor",
+  "BTN_COPY_LOGS": "Copiar registros",
+  "BTN_COPY_LOGS_TOOLTIP": "Copiar registros al portapapeles para compartir",
+  "LABEL_VIDEO_DEBUG": "Información de depuración de video",
+  "LABEL_VIDEO_DEBUG_TOOLTIP": "Detalles técnicos sobre el elemento de video seleccionado actualmente",
+  "VIDEO_DEBUG_EMPTY": "No hay pestaña seleccionada o no se detectó ningún video.",
+  "LABEL_HISTORY": "Historial completo",
+  "LABEL_HISTORY_TOOLTIP": "Registro cronológico de todos los comandos de sincronización en la sala",
+  "HISTORY_EMPTY": "Sin actividad aún",
+  "LABEL_LOGS": "Logs (Últimos 50)",
+  "LABEL_LOGS_TOOLTIP": "Registros técnicos de conexión para depuración",
+  "BTN_CLEAR": "LIMPIAR",
+  "BTN_CLEAR_TOOLTIP": "Limpiar salida de registros",
+  "LABEL_GITHUB": "Repositorio de GitHub",
+  "BTN_ONBOARDING_SKIP": "Omitir",
+  "BTN_ONBOARDING_SKIP_TOOLTIP": "Omitir el tutorial",
+  "BTN_ONBOARDING_NEXT": "Siguiente",
+  "BTN_ONBOARDING_NEXT_TOOLTIP": "Ir al siguiente paso",
+  "ONBOARDING_1_TITLE": "¡Bienvenido a KoalaSync!",
+  "ONBOARDING_1_TEXT": "Mira videos junto a tus amigos en perfecta sincronización, sin importar dónde estén. ¡Hagamos un recorrido rápido!",
+  "ONBOARDING_2_TITLE": "1. Crear una sala",
+  "ONBOARDING_2_TEXT": "Comienza aquí. Crea una sala y comparte el enlace de invitación con tus amigos.",
+  "ONBOARDING_3_TITLE": "2. Seleccionar video",
+  "ONBOARDING_3_TEXT": "Navega aquí para seleccionar el video que deseas sincronizar. Reproduce, pausa y busca: todos permanecen sincronizados.",
+  "ONBOARDING_4_TITLE": "3. Personalizar",
+  "ONBOARDING_4_TEXT": "Elige un nombre de usuario divertido para que tus amigos sepan quién eres.",
+  "ONBOARDING_5_TITLE": "¡Todo listo!",
+  "ONBOARDING_5_TEXT": "Hora de preparar las palomitas. ¡Disfruta viendo con tus amigos!",
+  "ERR_CONN_TIMEOUT": "Tiempo de conexión agotado. Inténtalo de nuevo.",
+  "ERR_INVALID_SERVER_URL": "Formato de URL de servidor no válido.",
+  "ERR_IDENTITY_NOT_LOADED": "Identidad no cargada aún. Espera un momento e inténtalo de nuevo.",
+  "ERR_NO_PEERS_TIME": "No hay otros participantes con posición conocida. Cambia a 'Traerlos a mi posición'.",
+  "ERR_NO_VIDEO_TAB": "No se pudo conectar a la pestaña de video.",
+  "SITE_ACCESS_REQUIRED": "Tu navegador está bloqueando KoalaSync en {host}. Haz clic en «Permitir acceso». Si no aparece ningún diálogo, permite KoalaSync en este sitio desde los permisos de extensiones o del sitio.",
+  "BTN_RETRY_ACCESS": "Permitir acceso",
+  "ERR_SELECT_VIDEO": "¡Selecciona un video primero!",
+  "TOAST_INVITE_COPIED": "¡Enlace de invitación copiado!",
+  "TOAST_COPY_FAILED": "Error al copiar al portapapeles",
+  "TOAST_LOBBY_SKIPPED": "Sala de espera de episodio omitida.",
+  "TOAST_LOBBY_SKIP_FAILED": "Error al omitir la sala de espera.",
+  "TOAST_LOGS_COPIED": "¡Copiado!",
+  "TOAST_PEER_JOINED": "{name} se ha unido a la sala",
+  "TOAST_PEER_LEFT": "{name} ha salido de la sala",
+  "TOAST_PEER_ACTION": "{name} ha {action}",
+  "STATUS_CONNECTED": "Conectado",
+  "STATUS_RECONNECTING": "Reconectando...",
+  "STATUS_CONNECTING": "Conectando...",
+  "STATUS_FAILED": "Error",
+  "STATUS_DISCONNECTED": "Desconectado",
+  "STATUS_IDLE": "Listo para conectar",
+  "STATUS_IDLE_TOOLTIP": "KoalaSync está listo. Únete o crea una sala para conectarte y empezar a sincronizar.",
+  "BTN_STATE_JOINING": "🚀 Uniéndose...",
+  "BTN_STATE_RECONNECTING": "🔄 Reconectando...",
+  "BTN_STATE_PLAYING": "▶ Reproduciendo...",
+  "BTN_STATE_PAUSING": "⏸ Pausando...",
+  "BTN_STATE_SYNCING_GROUP": "Sincronizando al grupo ({time})...",
+  "BTN_STATE_SYNCING": "Sincronizando...",
+  "BTN_STATE_SYNCED": "✅ ¡Sincronizado!",
+  "NOTIF_PLAY": "ha iniciado la reproducción",
+  "NOTIF_PAUSE": "ha pausado la reproducción",
+  "NOTIF_SEEK": "ha cambiado la posición del video",
+  "NOTIF_FORCE_PREPARE": "ha iniciado una sincronización forzada",
+  "NOTIF_FORCE_EXECUTE": "ha sincronizado a todos",
+  "DEBUG_NO_TAB": "No hay pestaña objetivo seleccionada.",
+  "DEBUG_COMM_FAIL": "No se pudo comunicar con el video de la pestaña.",
+  "EMPTY_PEERS_TITLE": "Sin participantes aún",
+  "EMPTY_PEERS_HINT": "Comparte tu enlace de invitación para comenzar",
+  "EMPTY_HISTORY_TITLE": "Sin actividad aún",
+  "EMPTY_HISTORY_HINT": "Reproduce, pausa o salta en el tiempo para ver el historial",
+  "EMPTY_LOGS_TITLE": "Sin registros",
+  "EMPTY_LOGS_HINT": "Los eventos de conexión aparecerán aquí",
+  "EMPTY_ROOMS_TITLE": "Sin salas activas",
+  "EMPTY_ROOMS_HINT": "Crea una sala o actualiza para buscar salas públicas",
+  "LABEL_YOU": "Tú",
+  "ONBOARDING_DONE": "¡Hecho!",
+  "LABEL_LOBBY_PEER_READY": "Listo",
+  "LABEL_LOBBY_PEER_LOADING": "Cargando...",
+  "LABEL_PASSWORD_PROTECTED": "Protegido con contraseña",
+  "LABEL_PEERS_COUNT": "{count} participantes",
+  "LABEL_CUSTOM_SERVER": "Servidor personalizado",
+  "BTN_STATE_CREATING": "🚀 Creando sala...",
+  "NOTIF_LOBBY_CANCEL_TITLE": "KoalaSync — Error al sincronizar episodio",
+  "NOTIF_LOBBY_CANCEL_MSG": "Sincronización automática cancelada: {reason}. Es posible que debas sincronizar manualmente.",
+  "LOBBY_CANCEL_TIMEOUT": "Tiempo de espera agotado",
+  "LOBBY_CANCEL_TIMEOUT_RECOVERED": "Tiempo de espera agotado (recuperado)",
+  "LOBBY_CANCEL_PEERS_LEFT": "Todos los demás participantes se han ido",
+  "LOBBY_CANCEL_TIMEOUT_PEERS_LOAD": "Tiempo de espera agotado: no todos los participantes cargaron el episodio",
+  "LOBBY_CANCEL_USER": "Cancelado por el usuario",
+  "NOTIF_ERROR_TITLE": "Error de KoalaSync",
+  "FOOTER_SUPPORT": "Support KoalaSync",
+  "FOOTER_REVIEW": "★ Valorar",
+  "FOOTER_SUPPORT_PROMPT": "¿Te gusta KoalaSync? ¡Deja una reseña!",
+  "LABEL_AUDIO_PROCESSING": "Procesamiento de audio",
+  "LABEL_AUDIO_PROCESSING_TOOLTIP": "Aplica efectos de audio como compresión a la reproducción de video",
+  "AUDIO_OPEN_SETTINGS": "Abrir",
+  "NEW_FEATURE_AUDIO": "Nuevo: Procesamiento de audio — ¡prueba el compresor!",
+  "NEW_FEATURE_THEME": "Nuevo: Temas — cambia al aspecto clásico o al grafito minimalista.",
+  "AUDIO_BACK": "← Volver",
+  "AUDIO_PAGE_TITLE": "Configuración de audio",
+  "AUDIO_MASTER_TOGGLE": "Procesamiento de audio",
+  "AUDIO_COMPRESSOR": "Compresor",
+  "AUDIO_COMPRESSOR_ENABLE": "Activado",
+  "AUDIO_PRESET": "Preajuste",
+  "AUDIO_PRESET_RECOMMENDED": "Recomendado",
+  "AUDIO_PRESET_DYNAMIC_RANGE": "Rango dinámico",
+  "AUDIO_PRESET_VOCAL_ENHANCEMENT": "Mejora de voz",
+  "AUDIO_PRESET_SMOOTH": "Suave",
+  "AUDIO_PRESET_CUSTOM": "Personalizado",
+  "AUDIO_PARAM_THRESHOLD": "Umbral (Threshold)",
+  "AUDIO_PARAM_KNEE": "Codo (Knee)",
+  "AUDIO_PARAM_RATIO": "Relación (Ratio)",
+  "AUDIO_PARAM_ATTACK": "Ataque (Attack)",
+  "AUDIO_PARAM_RELEASE": "Liberación (Release)",
+  "AUDIO_EQUALIZER": "Ecualizador",
+  "AUDIO_COMING_SOON": "Próximamente",
+  "BTN_RESTART_TOUR": "Reiniciar tutorial",
+  "BTN_RESTART_TOUR_TOOLTIP": "Reiniciar el tutorial de inicio",
+  "HINT_SELECT_VIDEO": "¡Selecciona tu video aquí!",
+  "OPTION_TITLE_PRIVACY_FULL": "Enviar título completo",
+  "OPTION_TITLE_PRIVACY_EPISODE": "Enviar ID de episodio",
+  "OPTION_TITLE_PRIVACY_HIDDEN": "No enviar",
+  "LABEL_PRIVACY_SETTINGS": "Ajustes de privacidad",
+  "LABEL_PRIVACY_SETTINGS_TOOLTIP": "Elige qué títulos de pestaña y multimedia se envían a la sala.",
+  "LABEL_SEND_TAB_TITLE": "Enviar título de pestaña",
+  "LABEL_SEND_TAB_TITLE_TOOLTIP": "Envía a la sala el título de la pestaña del navegador seleccionada.",
+  "LABEL_MEDIA_TITLE_PRIVACY": "Título multimedia",
+  "LABEL_MEDIA_TITLE_PRIVACY_TOOLTIP": "Elige cómo se envían los títulos multimedia a la sala.",
+  "LABEL_SETTINGS_GROUP_PROFILE": "Perfil y Apariencia",
+  "LABEL_SETTINGS_GROUP_PROFILE_TOOLTIP": "Cambia tu nombre de usuario, tema y preferencias de idioma.",
+  "LABEL_SETTINGS_GROUP_SYNC": "Reproducción y Sincronización",
+  "LABEL_SETTINGS_GROUP_SYNC_TOOLTIP": "Personaliza la reproducción, las notificaciones y las preferencias de audio."
+}